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Introduction 


The Microsoft® run-time library is a set of more than 550 ready-to-use functions 
and macros designed for use in C and C++ programs. The run-time library makes 
programming easier by providing 


= Fast and efficient routines to perform common programming tasks (such as 
string manipulation), sparing you the time and effort needed to write such 
routines 


=" Reliable methods of performing operating-system functions (such as opening 
and closing files) 


The run-time library is important because it provides basic functions not provided 
by the C and C++ languages themselves. These functions include input and output, 
memory allocation, process control, graphics, and many others. 


This book describes the run-time library routines included with Microsoft C/C++ 
version 7.0. These comprise all of the routines included with earlier versions of 
Microsoft C, as well as many new routines. 


About the Microsoft. Run-Time Library 


The Microsoft run-time library contains routines and features that support Ameri- 
can National Standards Institute (ANSI) C and UNIX C compatibility, DOS and 
Microsoft Windows programming, and sophisticated graphics programming. 


To ease the task of transporting programs between operating systems and com- 
pilers, the description of each run-time library routine includes a compatibility 
section. A routine with full compatibility has the following entries: 


Standards: ANSI, UNIX 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 


(In this book, references to UNIX systems also encompass XENIX@ and other 
UNIX-like systems.) 
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ANSI! C Compatibility 


The run-time library routines are designed for compatibility with the ANSI C 
standard, which the Microsoft C and C++ compilers support. Functions that are 
ANSI C compatible are marked as ANSI in the compatibility section. 


Type Checking 


The major innovation of ANSI C is to permit argument-type lists in function proto- 
types (declarations). Given the information in the function prototype, the compiler 
can check later references to the function to make sure that the references use the 
correct number and type of arguments and the correct return value. 


To take advantage of the compiler’s type-checking ability, the include files that ac- 
company the run-time library have been expanded. In addition to the definitions 
and declarations required by library routines, the include files now contain func- 
tion declarations with argument-type lists. Several new include files have also — 
been added. The names of these files are chosen to maximize compatibility with 
the ANSI C standard and with UNIX and XENIX names. 


Underscores and OLDNAMES.LIB 


With Microsoft C/C++, all Microsoft-specific run-time functions, constants, varia- 
bles, type definitions, structures, and macros (such as, respectively, _ open, 

_ VRES16COLOR, _ cpumode, _HEAPINFO, _ heapinfo, and __ isascii) are 
ANSI compatible. The Microsoft-specific run-time functions, constants, variables, 
type definitions, and structures begin with a single underscore; Microsoft-specific 
run-time macros begin with two underscores. 


For compatibility with previous versions of Microsoft C, Microsoft C/C++ pro- 
vides a library named OLDNAMES.LIB, which contains alias records mapping 
the names to the new names. For instance, open is mapped to _ open. 


You have to link with OLDNAMES.LIB to link Microsoft C/C++ programs with 
object files created by previous versions of Microsoft C. However, by default the 
compiler emits a library search record—the only time you must link explicitly 
with OLDNAMES.LIB is under one of the following situations: 


= Compiling with a combination of the default /Ze option (use Microsoft exten- 
sions) and the /Z] option (omit default library name from object file) 


=» Compiling with the default /Ze option (use Microsoft extensions) and a combi- 
nation of the /link option (linker-control) and the /NOD option (no default- 
library search) 


For more information on the CL command-line options, see Chapter 13 of 
Environment and Tools (in the Microsoft C/C++ version 7.0 documentation set). 
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Note The compiler views a structure with both an old name and a new name as 
two different types; you cannot copy from an old type to a new type. Also, old pro- 
totypes that take struct pointers use the old struct names in the prototype. So, you 
must be consistent—match the old names for routines with the old names for the 
parameters and be similarly consistent with the new routine names and parameters. 


UNIX C Compatibility 


Most of the functions in the Microsoft run-time library are compatible with like- 
named UNIX routines. For additional compatibility, the math library functions 
have been extended to provide exception handling in the same manner as the 
UNIX System V math functions. Functions that are UNIX and XENIX compatible 
are marked as UNIX in the compatibility section. 


DOS and Microsoft Windows... Programming 


QuickWin 


Microsoft run-time library routines are designed to maintain maximum compati- 
bility between DOS, Windows, and UNIX or XENIX systems. The run-time 
library offers a number of operating-system interface routines that allow you to 
take advantage of specific DOS and Windows features. Functions that are DOS 
and Windows compatible are marked, respectively, as DOS and WIN in the com- 
patibility section. Note that for Windows the compatibility section also contains 
information on dynamic-link library (DLL) compatibility. 


Many run-time library functions are designed to work with the Microsoft DOS 
Extender. The DOS Extender 1s a shell between a program and DOS that allows 
the program to run in the 32-bit flat memory model. Currently, the Microsoft C 
and C++ compilers are hosted under the DOS Extender; when Microsoft C/C++ 
provides 32-bit targeting, you can use the functions listed as DOS32X compatible 
to develop and run 32-bit flat model programs under DOS. 


The Microsoft run-time library now contains several QuickWin functions that 
make it possible to compile non-Windows DOS programs as simple text-only 
Windows applications. DOS programs compiled with the /Mq compiler option 
have a limited Windows user interface, including a standard menu bar, standard 
online help (for the QuickWin features), and a client (or application) window with 
a child (document) window for the C input/output streams stdin, stdout, and 
stderr. You can also add other child windows of your own. QuickWin applica- 
tions support the Windows Clipboard, and you can use standard C functions to 
write to and read from a Quick Win application’s windows, which behave as 
streams. Functions that are Quick Win compatible are marked as QWIN in the 
compatibility section. 
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Expanded Graphics Library 


The Microsoft run-time library contains more than one hundred graphics routines. 
The core of this library consists of several dozen low-level graphics routines that 
allow your programs to select video modes, set points, draw lines, change colors, 
and draw shapes such as rectangles and ellipses. You can display real-valued data, 
such as floating-point values, within windows of different sizes by using various 
coordinate systems. 


The graphics library includes presentation graphics and fonts. The presentation- 
graphics library provides powerful tools for adding presentation-quality graphics 
to your programs. These routines can display data as a variety of graphs, including 
pie charts, bar and column charts, line graphs, and scatter diagrams. 


The fonts library allows your programs to display various styles and sizes of text 
in graphics images or charts. You can use font-manipulation routines with any 
graphics routines that display text, including presentation graphics. 


About This Book 


This book provides a guide to the run-time library provided with Microsoft C/C++. 


This book has two parts. Part 1, “Overview,” introduces the Microsoft run-time li- 
brary. It describes general rules for using the library and summarizes the main cate- 
gories of library routines. Part 1 contains the following chapters: 


= Chapter 1, “Using the Run-Time Library,” gives general rules for under- 
standing and using library routines and mentions special considerations that 
apply to certain routines. It is recommended that you read this chapter before 
using the run-time library; you may also want to turn to Chapter 1 when you 
have questions about library procedures. 


= Chapter 2, “Run-Time Routines by Category,” lists the library routines by cate- 
gory and discusses considerations that apply to each category. This chapter 
makes it easy to locate routines by task. Once you find the routine you want, 
turn to the reference page in Part 2 for a detailed description. 


= Chapter 3, “Global Variables and Standard Types,” describes variables and 
types that are used by library routines. Global variables and standard types are 
also described in the reference descriptions of the routines that use them. 


Part 2, “Run-Time Functions,” describes the library routines in alphabetical order. 
Once you are familiar with the run-time library rules and procedures, you will 
probably use this part most often. 
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Other Books of Interest 


The following books cover a variety of topics that you may find useful. They are 
listed only for your convenience. With the exception of its own publications, 
Microsoft does not endorse these books or recommend them over others on the 
Same subject. 


=» Barkakati, Nabajyoti. The Waite Group’s Microsoft C Bible. Indianapolis, IN: 
Howard W. Sams, 1988. 


A topical guide to the Microsoft C run-time library. A similar volume is availa- 
ble for the Microsoft QuickC® product. 


= Campbell, Joe. C Programmer’s Guide to Serial Communications. Indi- 
anapolis, IN: Howard W. Sams & Company, 1987. 


A comprehensive guide to the specialized area of serial communication pro- 
gramming in C. 
= Christian, Kaare. C++ Programming. Redmond, WA: Microsoft Press, 1992. 


An introduction to object-oriented programming concepts, C++ fundamentals, 
and Microsoft C/C++ version 7.0, particularly the Foundation class libraries. 


= Harbison, Samuel P., and Guy L. Steele, Jr. C: A Reference Manual, 2d ed. 
Englewood Cliffs, NJ: Prentice Hall, 1987. 


A comprehensive guide to the C language and the standard library. 


= Kernighan, Brian W., and Dennis M. Ritchie. The C Programming Language, 
2d ed. Englewood Cliffs, NJ: Prentice Hall, 1988. 


The first edition of this book is the classic definition of the C language. The 
second edition includes new information on the ANSI C standard. 


= Lafore, Robert. Microsoft C Programming for the IBM. Indianapolis, IN: 
Howard W. Sams & Company, 1987. 


The first half of this book teaches C. The second half concentrates on specifics 
of the PC environment, such as BIOS calls, memory, and video displays. 

=# Mark Williams Company. ANSI C: A Lexical Guide. Englewood Cliffs, NJ: 
Prentice Hall, 1988. 
A dictionary-style guide to the ANSI C standard. 

= Plauger, P. J., and Jim Brodie. ANS/ and ISO Standard C: A Guide for 
Programmers. Redmond, WA: Microsoft Press, 1992. 


A reference to the ANSI and ISO C implementation by the secretary and chair- 
man of the ANSI- and ISO-authorized C Programming Language Standards 
Committee. 
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# Plum, Thomas. Reliable Data Structures in C. Cardiff, NJ: Plum Hall, 1985. 
An intermediate-level look at data structures using the C language. 

= Plum, Thomas, and Jim Brodie. Efficient C. Cardiff, NJ: Plum Hall, 1985. 
A guide to techniques for increasing the efficiency of C programs. 


= Press, William H., Brian P. Flannery, Saul A. Teukolsky, and William T. 
Vetterling. Numerical Recipes in C: The Art of Scientific Computing. New 
York: Cambridge University Press, 1988. 


A comprehensive look at numerical techniques using the C language. 


= Schustack, Steve. Variations in C: Building Professional Applications with 
Microsoft C. Second Edition. Redmond, WA: Microsoft Press, 1989. 


An intermediate-level guide to developing business applications in C. 
=» Ward, Robert. Debugging C. Indianapolis, IN: Que Corporation, 1986. 
An advanced guide to the theory and practice of debugging C programs. 
# Wilton, Richard. Programmer’s Guide to PC and PS/2 Video Systems: Maxi- 


mum Video Performance from the EGA, VGA, HGC, & MCGA. Redmond, 
WA: Microsoft Press, 1987. 


An advanced guide to all the PC and PS/2 video modes. 


Document Conventions 


This book uses the following typographic conventions: 
Example Description 


STDIO.H Uppercase letters indicate filenames, segment names, 
registers, and terms used at the operating-system 
command level. 


char, _setcolor, Bold type indicates C and C++ keywords, operators, 

__far language-specific characters, and library routines. 
Within discussions of syntax, bold type indicates that 
the text must be entered exactly as shown. 


Many functions and constants begin with either a 
single or double underscore. These are part of the 
name and are mandatory. For example, to have the 
__cplusplus manifest constant be recognized by the 
compiler, you must enter the leading double 
underscore. 


expression Words in italics indicate placeholders for information 
you must supply, such as a filename. 


Example 


[loption || 
#pragma pack {112} 


dFinclude <io.h> 
CL [loption...]] file... 
while() 

{ 

} 

CTRL+ENTER 


“argument” 


"C string" 


Color Graphics 
Adapter (CGA) 
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Description 


Items inside double square brackets are optional. 


Braces and a vertical bar indicate a choice among two 
or more items. You must choose one of these items 
unless double square brackets ({] []) surround the 
braces. 


This font is used for examples, user input, program 
output, and error messages in text. 


Three dots (an ellipsis) following an item indicate that 
more items having the same form may appear. 


A column or row of three dots tells you that part of an 
example program has been intentionally omitted. 


Small capital letters are used to indicate the names of 
keys on the keyboard. When you see a plus sign (+) 
between two key names, you should hold down the 
first key while pressing the second. 


The carriage-return key, sometimes marked as a bent 
arrow on the keyboard, 1s called ENTER. 


Quotation marks enclose a new term the first time it 1s 
defined 1n text. 


Some C constructs, such as strings, require quotation 
marks. Quotation marks required by the language 
have the form " " and ' ' rather than“” and’ ’. 


The first time an acronym is used, it is usually spelled 
out. 


Note Microsoft documentation uses the term “DOS” to refer to both the 
MS-DOSe@ and IBM Personal Computer DOS operating systems. The name 
of a specific operating system is used to note features unique to that system. 
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Using the Run-Time Library 


This chapter provides basic information about how to use the Microsoft run-time 
library routines. It also describes some special rules, such as path-name and 
filename conventions, that apply to particular routines. You should read this chap- 
ter before you begin to use the run-time library routines, and you may also want to 
refer back to it if you have questions about library procedures. 


1.1 Calling Library Routines 


To use a library routine, simply call it in your program, just as if it is defined there. 
For instance, suppose you write the following program and name it SAMPLE.C: 


dEinclude <stdio.h> 
void main( void ) 
1 
DPINTT. “MiIchosory. Gy Cen” J; 
} 


The program prints Microsoft C/C++ by calling the printf routine, which is part 
of the run-time library. Calling a library routine normally involves two groups of 
files: 


= Header (“include’’) files that contain declarations, constants, and type defin1- 
tions required by library routines 


= Library files that contain the library routines in compiled form 


Header files and library files are both included with Microsoft C/C++. Header files 
are used when compiling, and library files are used when linking. 


You include the necessary header files in your program source code with #include 
directives. The description of each library routine in Part 2, “Run-Time Func- 
tions,” tells you what header file the routine requires. Since printf requires the 
STDIO.H header file, the SAMPLE.C program contains the following line: 


d#Finclude <stdio.h> 
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This line causes the compiler to insert the contents of STDIO.H into the source file 
SAMPLE.C. 


After you compile the source file, you link the resulting object (OBJ) file with the 
appropriate library (.LIB) file to create an executable (.EXE) file. Your object file 
contains the name of every routine that your program calls, including library 
routines. If a routine is not defined in your program, the linker searches for its 
code in a library file and includes that code in the executable file. 


Normally, the code for standard library routines is contained in the “default li- 
brary” that you create when installing Microsoft C/C++. Since the linker automat- 
ically searches the default library, you do not need to specify that library’s name 
when linking your program. The following command links the example program 


_ with the default library: 


link sample,,,; 


If you call a library routine that is not contained in the default library, you must 
give the linker the name of the library file that contains the routine. For instance, if 
your program uses a Microsoft graphics routine, you would link the program using 
a line that includes GRAPHICS.LIB: 


link sample,,, graphics.1lib; 


For more information about installing libraries and linking, see Getting Started 
and Part 3 of Environment and Tools (both are in the Microsoft C/C++ version 7.0 
documentation set) or consult the installation documentation for your compiler. 


1.2 Using Header Files 


As stated in the previous section, you should include header files when using 
library routines. This section describes particular reasons why header files are 
required. 


Including Necessary Definitions 


Many run-time library routines use constants, type definitions, or macros defined 
in a header file. To use the routine, you must include the header file containing the 
needed definition(s). The following list gives examples: 


Definition Example 


Macro If a library routine is implemented as a macro, the macro 
definition appears in a header file. For instance, the toupper 
macro is defined in the header file CTYPE.H. 
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Definition Example 


Manifest constant Many library routines refer to constants that are defined in 
header files. For instance, the _ open routine uses constants such 
as _O_CREAT, which is defined in the header file FCNTL.H. 

Type definition Some library routines return a structure or take a structure as an 


argument. For example, stream input/output routines use a 
structure of type FILE, which is defined in STDIO.H. 


Including Function Declarations 


The run-time library header files also contain function declarations for every func- 
tion in the run-time library. These declarations are in the style recommended by 
the ANSI C standard. Given these declarations, the compiler can perform “type 
checking” on every reference to a library function, making sure that you have used 
the correct return type and arguments. Function declarations are sometimes called 
“prototypes,” since the declaration serves as a prototype or template for every sub- 
sequent reference to the function. 


A function declaration lists the name of the function, its return type, and the 
number and type of its arguments. For instance, this is the declaration of the 
pow library function from the header file MATH.H: 


double pow( double x, double y ); 


The example declares that pow returns a value of type double and takes two argu- 
ments of type double. Given this declaration, the compiler can check every refer- 
ence to pow in your program to ensure that the reference passes two double 
arguments to pow and takes a return value of type double. 


The compiler can perform type checking only for function references that appear 
after the function declaration. Because of this, function declarations normally ap- 
pear near the beginning of the source file, prior to any use of the functions they 
declare. 


Function declarations are especially important for functions that return a value of 
some type other than int, which is the default. For example, the pow function re- 
turns a double value. If you do not declare such a function, the compiler treats its 
return value as int, which can cause unexpected results. 


It is also a good practice to provide declarations for functions that you write. If 

you do not want to type the declarations by hand, you can generate them automat- 
ically by using the /Zg compiler option. This option causes the compiler to 
generate ANSI-standard function declarations for every function defined in the cur- 
rent source file. Redirect this output to a file, then insert the file near the beginning 
of your source file. 
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Your program can contain more than one declaration of the same function, as long 
as the declarations do not conflict. This is important if you have old programs 
whose function declarations do not contain argument-type lists. For instance, if 
your program contains the declaration 


char *calloc( ); 


you can later include the following declaration: 


char *calloc(unsigned, unsigned); 


Because the two declarations are compatible, even though they are not identical, 
no conflict occurs. The second declaration simply gives more information about 
function arguments than the first. A conflict would arise, however, if the declara- 
tions gave a different number of arguments or gave arguments of different types. 


Some library functions can take a variable number of arguments. For instance, the 
printf function can take one argument or several. The compiler can perform only 

limited type checking on such functions, a factor that affects the following library 
functions: 


= In calls to __cprintf, _cscanf, printf, and scanf, only the first argument (the for- 
mat string) 1s type checked. 


# In calls to fprintf, fscanf, _snprintf, sprintf, and sscanf, only the first two ar- 
guments (the file or buffer and the format string) are type checked. 


= In calls to __open, only the first two arguments (the path name and the _open 
flag) are type checked. 


= In calls to _sopen, only the first three arguments (the path name, the _ open 
flag, and the sharing mode) are type checked. 


= In calls to __execl, _execle, _execlp, and _ execlpe, only the first two argu- 
ments (the path name and the first argument pointer) are type checked. 


= In calls to _spawnl, _spawnle, _spawnlp, and _spawnlpe, only the first three 
arguments (the mode flag, the path name, and the first argument pointer) are 
type checked. 


1.3 Paths and Filenames 


Many library routines take strings representing paths and filenames as arguments. 
If you plan to transport your programs to the UNIX (or XENIX) operating system, 
you should remember that UNIX uses path-name and filename conventions that 
are different from those used by DOS. If you do not plan to transport your pro- 
grams to UNIX, you can skip this section. 


Using the Run-Time Library 9 


Case Sensitivity 

The DOS operating system is not case sensitive (it does not distinguish between 
uppercase and lowercase letters). Thus, SAMPLE.C and Sample.C refer to the 
same file. However, the UNIX operating system is case sensitive. In UNIX, 
SAMPLE.C and Sample.C refer to different files. To transport programs to UNIX, 
choose path names and filenames that work correctly in UNIX, since either case 
works in DOS. For instance, the following directives are identical in DOS, but 
only the second works in UNIX: 


4Hinclude <STDIO.H> 
4Ainclude <stdio.h> 


Subdirectory Conventions 
Under UNIX, certain header files are normally placed in a subdirectory named 
SYS. Microsoft C follows this convention to ease the process of transporting pro- 


grams to UNIX. If you do not plan to transport your programs, you can place the 
SYS header files elsewhere. 


Path-Name Delimiters 

UNIX uses the slash (/) in path names, while DOS uses the backslash (\). To trans- 
port programs to UNIX, it is advantageous to use path-name delimiters that are 
compatible with UNIX whenever possible. 


1.4 Choosing Between Functions and Macros 


This book uses the words “routine” and “function” interchangeably. However, the 
term “routine” actually encompasses both functions and macros. Because func- 
tions and macros have different properties, you should pay attention to which form 
you are using. The descriptions in the reference section indicate whether routines 
are implemented as functions or as macros. 


Most routines in the Microsoft run-time library are functions. They consist of com- 
piled C code or assembled Microsoft Macro Assembler (MASM) code. However, 
a few library routines are implemented as macros that behave like functions. You 
can pass arguments to library macros and invoke them in the same way you in- 
voke functions. 


The main benefit of using macros is faster execution time. Every library macro is 
defined with a #define directive in a header file. A macro is expanded (replaced 
by its definition) during preprocessing, creating inline code. Thus, macros do not 
have the overhead associated with function calls. On the other hand, each use of a 
macro inserts the same code in your program, whereas a function definition occurs 
only once regardless of how many times it is called. Functions and macros thus 
offer a trade-off between speed and size. 
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Apart from speed and size issues, macros and functions have some other important 
differences: 


= Some macros treat arguments with side effects incorrectly when the macro eval- 
uates its arguments more than once (see the example that follows this list). Not 
every macro has this effect. To determine if a macro handles side effects as 
desired, examine its definition in the appropriate header file. 


= A function name evaluates to an address, but a macro name does not. Thus, you 
cannot use a macro name in contexts requiring a function pointer. For instance, 
you can declare a pointer to a function, but you cannot declare a pointer to a 
macro. 


= You can declare functions, but you cannot declare macros. Thus, the compiler 
cannot perform type checking of macro arguments as it does of function argu- 
ments. However, the compiler can detect when you pass the wrong number of 
arguments to a macro. | 


The following example demonstrates how some macros can produce unwanted 
side effects. It uses the toupper routine. 


#Hinclude <ctype.h> 


TAL. aS. MS 
a = toupper(at+); 


The example increments a when passing it as an argument to the toupper 
routine, which is implemented as a macro. It is defined in CTYPE.H: 


#define toupper(c) ( (islower(c)) ? _toupper(c) : (c) ) 


The definition uses the conditional operator (? :). The conditional expression eval- 
uates the argument c twice: once to check if it is lowercase and again to create the 
result. This macro evaluates the argument a++ twice, increasing a by 2 instead of 
1. As a result, the value operated on by islower differs from the value operated on 
by _ toupper. 


Like some other library routines, toupper is provided in both macro and function 
versions. The header file CTYPE.H not only declares the toupper function but 
also defines the toupper macro. 


Choosing between the macro version and function version of such routines is easy. 
If you wish to use the macro version, you can simply include the header file that 
contains the macro definition. Because the macro definition of the routine always 
appears after the function declaration, the macro definition normally takes prece- 
dence. Thus, if your program includes CT YPE.H and then calls toupper, the com- 
piler uses the toupper macro: 
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#Finclude <ctype.h> 


nt tdo = “ms 
a = toupper(a); 


You can force the compiler to use the function version of a routine by enclosing 
the routine’s name in parentheses: 


#Hinclude <ctype.h> 


Ta = Ms 
a = (toupper) (a); 


Because the name toupper is not immediately followed by a left parenthesis, the 
compiler cannot interpret it as a macro name. It must use the toupper function. 


A second way to do this is to “undefine” the macro definition with the #undef 
directive: 


fHinclude <ctype.h> 
#tundef toupper 


Since the macro definition no longer exists, subsequent references to toupper use 
the function version. 


A third way, not generally recommended, to make sure the compiler uses the func- 
tion version is to declare the function explicitly: 


#Hinclude <ctype.h> 
int toupper(int _c); 


Since this function declaration appears after the macro definition in CTYPE.H, it 
causes the compiler to use the toupper function. 


1.5 Stack Checking on Entry 


For certain library routines, the compiler performs stack checking on entry. (The 
“stack” is a memory area used for temporary storage.) Upon entry to such a 
routine, the stack is checked to determine if it has enough room for the local varia- 
bles used by that routine. If it does, space is allocated by adjusting the stack 
pointer. Otherwise, a “stack overflow” run-time error occurs. If stack checking is 
disabled, the compiler assumes there is enough stack space; if there is not, you 
might overwrite memory locations in the data segment and receive no warning— 
unpredictable program behavior may result. 


12 


Run-Time Library Reference 


Typically, stack checking is enabled only for functions with large local-variable re- 
quirements (more than about 150 bytes), since there is enough free space between 
the stack and data segments to handle functions with smaller requirements. If the 
function is called many times, stack checking slows execution slightly. 


Stack checking is enabled for the following library functions: 


_execvp scanf system 
_execvpe _Spawnvp vprintf 
fprintf _Spawnvpe _write 
fscanf sprintf 
printf sscanf 


You can enable or disable stack checking with the /Gs and /Ge compiler options 
(see Chapter 13 of Environment and Tools) or the check_ stack pragma (see 
Chapter 7 of the C Language Reference). Both books are in the Microsoft C/C++ 
version 7.0 documentation set. 


1.6 Handling Errors 


Many library routines return a value that indicates an error condition. To avoid un- 
expected results, your code should always check such error values and handle all 
of the possible error conditions. The description of each library routine in the refer- 
ence section lists the routine’s return value(s). 


Some library functions do not have a set error return. These include functions that 
return nothing and functions whose range of return values makes it impossible to 
return a unique error value. 


To aid in error handling, some functions set the value of a global variable named 
errno. If the reference description of a routine states that it sets the errno variable, 
you can use errno in two ways: 


= Compare errno to the values defined in the header file ERRNO.H. 


= Handle errno with the perror or strerror library routine. The perror routine 
prints a system error message to the standard error (stderr). The strerror 
routine stores the same information in a string for later use. 


When you use errno, perror, and strerror, remember that the value of errno 
reflects the error value for the last call that set errno. To avoid confusion, you 
should always test the return value to verify that an error actually occurred. Once 
you determine that an error has occurred, use strerror or perror immediately. 
Otherwise, the value of errno may be changed by intervening calls. 
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Library math routines set errno by calling the _matherr or _ matherrl library 
routine; both are described in the reference section. If you wish to handle math 
errors differently from these routines, you can write your Own routine and name 
it_matherr or _matherrl. Your routine must follow the rules listed in the 
_matherr reference description. 


The ferror library routine allows you to check for errors in stream input/output 
operations. This routine checks if an error indicator has been set for a given 
stream. Closing or rewinding the stream automatically clears the error indicator. 
You can also reset the error indicator by calling the clearerr library routine. 


The feof library routine tests for end-of-file on a given stream. An end-of-file con- 
dition in low-level input and output can be detected with the _ eof routine or when 
a _read operation returns 0 as the number of bytes read. 


The _ grstatus library routine allows you to check for errors after calling certain 
graphics library operations. See the reference page on the _ grstatus function for 
details. 


1.7 Operating-System Considerations 


The library routines listed in this section behave differently under different 
operating-system versions. For more information on an individual routine, see the 
description of that routine in the reference section. 


Routine Restrictions 

_locking These routines are effective only in DOS versions 3.0 and later. 

_sopen 

_fsopen 

_ dosexterr The _dosexterr routine provides error handling for system call 0x59 
(get extended error) in DOS versions 3.0 and later. 

_dup The _dup and _dup2 routines can cause unexpected results in DOS 

_dup2 versions earlier than 3.0. If you use _dup or _dup2 to create a 


duplicate file handle for stdin, stdout, stderr, stdaux, or stdprn, 
calling the _ close function with one handle causes errors in later I/O 
operations that use the other handle. This anomaly does not occur in 
DOS versions 3.0 and later. 


_exec When using the _exec and _ spawn families of functions under DOS 
_spawn versions earlier than 3.0, the value of the arg0 argument (or argv[0] 
to the child process) is not available to the user; a null string ( "" ) 


is stored in that position instead. In DOS versions 3.0 and later, the 
argO argument contains the complete command path. 
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Microsoft C/C++ defines global variables that indicate the version of the current 
operating system. You can use these to determine the operating-system version in 
which a program is executing. See Chapter 3, “Global Variables and Standard 
Types,” for more information. 


1.8 Floating-Point Support 


Microsoft math library routines require floating-point support to perform calcula- 

tions with real numbers (numbers that can contain fractions). This support can be 

provided by the floating-point libraries that accompany your compiler software or 
by an 8087, 80287, or 80387 coprocessor. The names of the functions that require 
floating-point support are listed below: 


acos cos _fmodl _powl 
_acosl _cosl _fmsbintoieee sin 

asin cosh _fpreset _sinl 
_asinl _coshl frexp sinh 
atan _dieeetomsbin _frexpl _sinhl 
_atanl difftime _gevt sqrt 
atan2 _dmsbintoieee _hypot _sqrtl 
_atan2] _ecvt _hypotl _Status87 
atof exp Idexp strtod 
_atold _expl _Idexpl _strtold 
Bessel fabs log tan 
_cabs _fabsl _logl _tanl 
_cabsl _fevt log10 tanh 
ceil _fieeetomsbin _log101 _tanhl 
_ceill floor modf 

_clear87 _floorl _modfl 

_control87 fmod pow 


Note that the Bessel routine does not correspond to a single function, but to 12 
functions named _j0, _j1, _jn, _y0, _y1, _yn, _jOl, _j11, _ jnl, — yOl, _yll, and 
_ynl. Also note that the _clear87 and _control87 functions are not available with 
the /FPa compiler option. 
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Also requiring floating-point support is the printf family of functions (_ eprintf, 
fprintf, printf, _snprintf, sprintf, vfprintf, vprintf, _ vsnprintf, and vsprintf). 
These functions require support for floating-point input and output if used to print 
floating-point values. 


The compiler tries to detect whether floating-point values are used in a program so 
that supporting functions are loaded only if required. This behavior saves a consid- 
erable amount of space for programs that do not require floating-point support. 


When you use a floating-point type specifier in the format string for a printf or 
scanf call, make sure you specify floating-point values or pointers to floating- 
point values in the argument list. These must correspond to any floating-point type 
specifiers in the format string. The presence of floating-point arguments allows the 
compiler to detect that floating-point support code is required. If a floating-point 
type specifier is used to print an integer argument, for example, floating-point 
values will not be detected because the compiler does not actually read the format 
string used in the printf and scanf functions. For instance, the following program 
produces an error at run time: 


void main( void ) /* This example causes an error */ 
ie 

Long. <t -= 210i 

printt( "AT"; ft) 
} 


In the preceding example, the functions for floating-point support are not loaded 
because 


=" No floating-point arguments are given in the call to printf. 
= No floating-point values are used elsewhere in the program. 
As aresult, the following error occurs: 


Floating point not loaded 


Here is a corrected version of the above call to printf in which the long integer 
value is cast to double: 


void main( void ) /* This example works correctly */ 
{ 

long f = 1@L; 

printf("%f", (double) f); 
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1.9 Using Huge Arrays with Library Functions 


In programs that use small, compact, medium, and large memory models, the com- 
piler allows you to use arrays exceeding the 64K (kilobyte) limit of physical 
memory in these models by explicitly declaring the arrays as __huge. However, 
generally, you cannot pass huge pointers as arguments to run-time library func- 
tions. In the compact-model library used by compact-model programs and in the 
large-model library used by both large-model and huge-model programs, only the 
functions listed below use pointer arithmetic that works with huge items: 


bsearch _fmemmove memcmp 
fread _fmemset memcpy 
fwrite _halloc _memicmp 
_fmemccpy _hfree memmove 
_fmemchr _Ifind memset 
_fmemcmp _Isearch qsort 
_fmemcpy _memccpy 

_fmemicmp memchr 


With this set of functions, you can read from, write to, search, sort, copy, initial- 
ize, compare, or dynamically allocate and free huge arrays; the huge array can be 
passed without difficulty to any of these functions in a compact-, large-, or huge- 
model program. The model-independent routines in the above list (those beginning 
with _f) are available in all memory models. 


The memset, memcpy, and memcmp library routines are available in two ver- 
sions: as C functions and as intrinsic (inline) code. The function versions of these 
routines support huge pointers in compact and large memory models, but the in- 
trinsic versions do not support huge pointers. (The function version of such 
routines generates a call to a library function, whereas the intrinsic version inserts 
inline code into your program. For information on how to select the intrinsic ver- 
sions of library routines, see the /Oi option in Chapter 13 of Environment and 
Tools (in the Microsoft C/C++ version 7.0 documentation set) or consult you 
compiler documentation.) 
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Microsoft run-time library routines handle various kinds of tasks. If you know the 
type of task you need done, but don’t know exactly which routine to use, the cate- 
gorized lists of routines in this chapter can help. The descriptions here are intended 
only to give you a brief overview of the capabilities of the run-time library. For a 
complete description of the behavior, syntax, and use of each routine, see Part 2, 
“Run-Time Functions.” 


The main categories of library routines are 


= Buffer manipulation 

= Character classification and conversion 
= Data conversion 

= Directory control 

= File handling 

= Graphics 

= Input and output 

= Internationalization 

= Math 

=» Memory allocation 

= Process and environment control 
# QuickWin 

= Searching and sorting 

= String manipulation 

= System calls 

= Time 

= Variable-length argument lists 


= Virtual memory allocation 
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2.1 Buffer Manipulation 


The buffer-manipulation routines are useful for working with areas of memory on 
a byte-by-byte basis. A “buffer” is an array of bytes, similar to a character string. 
However, unlike strings, buffers are not usually terminated with a null character 
(’\0’) and can contain non-ASCII data. Therefore, the buffer-manipulation 
routines always take a length or count argument. Function declarations for the 
buffer-manipulation routines are given in the include files MEMORY.H and 
STRING.H, except for the _swab function, which appears in STDLIB.H. 


Routines beginning with _f are model independent; the _f stands for far. These 
routines are useful in writing mixed-model programs because they can be called 
from any program, regardless of the memory model being used. 


Routine Use 

_memcecpy, _fmemccpy Copy characters from one buffer to another until a given 
character or a given number of characters has been 
copied 

memchr, _fmemchr Return a pointer to the first occurrence, within a 
specified number of characters, of a given character in 
the buffer 

memcmp, _fmemcmp Compare a specified number of characters from two 
buffers 

memcpy, _fmemcpy Copy a specified number of characters from one buffer to 
another 


_memicmp, _fmemicmp Compare a specified number of characters from two 
buffers without regard to the case of the letters 
(uppercase and lowercase treated as equivalent) 


memmove, _fmemmove Copy a specified number of characters from one buffer to 
another 

memset, _ fmemset Use a given character to initialize a specified number of 
bytes in the buffer 

_swab Swaps bytes of data and stores them at the specified 
location 


When the source and target areas overlap, only the memmove and _fmemmove 
functions are guaranteed to copy the full source properly. (The memepy and 
_fmemcpy routines do not always copy the full source in such cases.) 
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2.2 Character Classification and Conversion 


The character classification and conversion routines allow you to test individual 
characters in a variety of ways and to convert between uppercase and lowercase 


characters. 


Routine 


isalnum 
isalpha 
__isascii 
iscntrl 
__iscsym 
__iscsymf 
isdigit 
isgraph 
islower 
isprint 
ispunct 
isspace 
isupper 
isxdigit 
__toascii 
tolower 
_tolower 
toupper 
_toupper 


Use 


Tests for alphanumeric character 

Tests for alphabetic character 

Tests for ASCII character 

Tests for control character 

Tests for letter, underscore, or digit 

Tests for letter or underscore 

Tests for decimal digit 

Tests for printable character except space 

Tests for lowercase character 

Tests for printable character 

Tests for punctuation character 

Tests for white-space character 

Tests for uppercase character 

Tests for hexadecimal digit 

Converts character to ASCII code 

Tests character and converts to lowercase if uppercase 
Converts character to lowercase (unconditional) 

Tests character and converts to uppercase if lowercase 
Converts character to uppercase (unconditional) 
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The classification routines identify characters by finding them in a table of classifi- 
cation codes. Using these routines to classify characters is generally faster than 
writing a test expression such as the following: 


if ((c >= @) || (c <= Qx7f)) 


All of these routines are implemented in two versions: as functions and as macros. 
The function prototypes and macro definitions appear in CTYPE.H. “Choosing 
Between Functions and Macros” on page 9 explains how to choose the appropriate 
version. The toupper and tolower functions are also declared in the STDLIB.H 


header file. 
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2.3 Data Conversion 


The data-conversion routines convert numbers to strings of ASCII characters and 
vice versa. These routines are implemented as functions, all of which are declared 
in the include file STDLIB.H. The atof function, which converts a string to a 
floating-point value, is also declared in MATH.H. 


Routine 


abs 
atof 
atoi 
atol 
_atold 
_ecvt 
_fevt 
_gevt 
_itoa 
labs 
_Itoa 
strtod 
strtol 
_ strtold 
strtoul 
_ultoa 


2.4 Directory Control 


Use 


Finds absolute value of integer 


Converts string to float 

Converts string to int 

Converts string to long 

Converts string to long double 

Converts double to string 

Converts floating-point number to string 
Converts floating-point number to string and stores it in a buffer 
Converts int to string 

Finds absolute value of long integer 
Converts long to string 

Converts string to double 

Converts string to a long integer 

Converts string to long double 

Converts string to an unsigned long integer 
Converts unsigned long to string 


The directory-control routines let a program access, modify, and obtain informa- 
tion about the directory structure. These routines are functions and are declared in 


DIRECT.H. 


Routine 


_chdir 


Use 


Changes current working directory 


_chdrive 

= getcwd 

_ getdrive 
_mkdir 
_rmdir 

_ searchenv 


Changes current drive 

Gets current working directory for the specified drive 
Gets current working directory 

Makes a new directory 

Removes a directory 

Searches for a given file on specified paths 


2.0 File Handling 
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The file-handling routines let you create, manipulate, and delete files. They also 
set and check file-access permissions. 


File-handling routines work on a file designated by a path name or by a “file 
handle,” an integer assigned by the operating system that identifies an open file. 
These routines modify or give information about the designated file. Most of them 
are declared in the include file IO.H, with the exceptions being the _ fstat and 

_ Stat functions (declared in SYS\STAT.H), the _ fullpath routine (declared in 
DIRECT.H), and the remove and rename functions (also declared in STDIO.H). 


Routine 


_ access 
_chmod 
_chsize 
_filelength 
_fstat 
_fullpath 
_isatty 
_locking 
_makepath 
_mktemp 
remove 
rename 
_setmode 
_splitpath 
_ Stat 
_umask 

_ unlink 


Use 


Checks file-permission setting 

Changes file-permission setting 

Changes file size 

Gets file length 

Gets file-status information on handle 

Makes an absolute path name from a relative path name 
Checks for character device 

Locks areas of file (available with DOS versions 3.0 and later) 
Merges path-name components into a single, full path name 
Creates unique filename 

Deletes file 

Renames file 

Sets file-translation mode 

Splits a path name into component pieces 

Gets file-status information on named file 

Sets default-permission mask 

Deletes file 


The _access, _chmod, _ fullpath, _makepath, remove, rename, _ splitpath, 
_Stat, and _ unlink routines operate on files specified by a path name or filename. 


The _ chsize, _ filelength, _ fstat, _isatty, _ locking, and _setmode routines work 
with files designated by a file handle. 


The _mktemp and _ umask routines have functions that are slightly different 
from the other routines. The _mktemp routine creates a unique filename; you can 
use _mktemp to create unique filenames that do not conflict with the names of ex- 
isting files. The _ umask routine sets the default permission mask for any new 
files created in a program. The mask can override the permission setting given in 
the _open or _ creat call for the new file. 
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2.6 Graphics 


The Microsoft run-time library includes a set of graphics routines that offer a wide 
variety of graphics functions, low-level graphics primitives, font functions, and 
presentation graphics (displays such as graphs and pie charts). 


Graphics functions are supplied in two libraries that must be explicitly linked with 
your program. The GRAPHICS.LIB library provides support for low-level 
graphics and character-font routines. The library PGCHART.LIB supports 
presentation-graphics routines. 


Low-Level Graphics and Character-Font Functions 


The low-level graphics and font functions are declared in the include file 
GRAPH.H. 


The library can be divided into the eight categories listed below, which correspond 
to the different tasks involved in creating and manipulating graphic objects. 


Category Task 


Configuring mode and environment Selects the proper display mode for the 
hardware and establishes memory areas for 
writing and displaying images 

Setting coordinates : Specifies the logical origin and the active 
display area within the screen 


Setting low-level graphics palettes Specifies a palette mapping for low-level 
graphics routines 

Setting attributes Specifies background and foreground colors, 
fill masks, and line styles for low-level 
graphics routines 


Creating graphics output Draws and fills figures 

Creating text output Writes text on the screen 

Transferring images Stores images in memory and retrieves them 
Displaying fonts Displays text in character fonts compatible 


with Microsoft Windows 


The following sections explain each of these categories. 


Configuring Mode and Environment 


Routines that configure the mode and environment establish the graphics or text 
mode of operation, determine the current graphics environment, and control the 
display of the cursor. 
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Routine Use 

_clearscreen Erases the screen and fills it with the current background 
color 

_ getactivepage Gets the current active page number 

_getbkcolor Returns the current background color 

_ getvideoconfig Obtains status of current graphics environment 

_getvisualpage Gets the current visual page number 

_grstatus Returns the status of the most recent graphics function call 

_setactivepage Sets memory area for the active page for writing images 

_setbkcolor Sets the current background color 

_settextrows Sets the number of text rows 

_setvideomode Selects an operating mode for the display screen 

_setvideomoderows Sets the video mode and the number of rows for text 
operations 

_setvisualpage Sets memory area for the current visual page 


Setting Coordinates 


The “set coordinates” routines set the current text or graphics position and convert 
pixel coordinates between the various graphics coordinate systems. 


The Microsoft graphics functions recognize three sets of coordinates: 


= Fixed physical coordinates 


= View coordinates defined by the application 


=» Window coordinates that can include floating-point values 


The functions in this category establish window and view coordinate systems and 
translate between physical, view, and window coordinate systems. 


Routine Use 

_ getcurrentposition Determines current position in view coordinates 
_getcurrentposition_w Determines current position in window coordinates 
_ getphyscoord Converts view coordinates to physical coordinates 
_getviewcoord Converts physical coordinates to view coordinates 


_getviewcoord_w Converts window coordinates to view coordinates 


_getviewcoord_wxy Converts window coordinates in _ wxycoord structure to 


view coordinates 


_getwindowcoord Converts view coordinates to window coordinates 
_setcliprgn Limits graphic output to a region of the screen 
_setvieworg Positions the view-coordinate origin 
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Routine Use 


_setviewport Limits graphics output to a region of the screen and 
positions the view-coordinate origin to the upper-left 
corner of that region 


_setwindow Defines a floating-point window coordinate system 


The default view coordinate system is identical to the physical screen coordinate 
system. The physical origin (0, 0) is always in the upper-left corner of the display. 
The x axis extends in the positive direction left to right, while the y axis extends in 
the positive direction top to bottom. 


The physical horizontal and vertical dimensions depend on the hardware display 
configuration and the selected mode. These values are accessible at run time by ex- 
amining the numxpixels and numypixels fields of the _ videoconfig structure re- 
turned by _ getvideoconfig. (The _ getvideoconfig routine is listed in the previous 
section. ) 


The _setvieworg function allows you to move the viewport origin to a new posi- 
tion relative to the physical screen. 


Routines that refer to coordinates on the physical screen or viewport require in- 
teger values. However, in real-world graphing applications, you might wish to use 
floating-point values, such as stock prices or average rainfall. The window coordi- 
nate system allows you to display graphics using floating-point values instead of 
integers. 


The _ getcurrentposition and _ getcurrentposition_ w routines allow you to 
determine the location of the current graphics-output point. 


The _ setcliprgn function defines a restricted active display area on the screen. 
The _setviewport function does the same thing and also resets the viewport origin 
to the upper-left corner of the restricted active display area. 


The physical coordinates of any view-coordinate point can be determined with the 
_getphyscoord function, and the view coordinates of any physical point can be 
determined with the _ getviewcoord function. 


The view coordinates of any window coordinate can be determined with the 
_getviewcoord_w and _ getviewcoord_ wxy functions. The window coordinates 
of any view coordinate can be determined with the _ getwindowcoord function. 


The _ setwindow function defines the current viewport as a real-coordinate win- 
dow bound by the specified floating-point values. 
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Setting Low-Level Graphics Palettes 
Use the low-level palette routines to select or remap color palettes. 


Routine Use 


_remapallpalette Changes all color indexes in the current palette 
_remappalette Changes a single color index in the current palette 
_Selectpalette Selects a predefined palette 


Some video modes support a “color palette,” which is a table of the color values 
that can be displayed together on the screen at any given time. A “color value” is a 
long integer representing a color that can be displayed on your system. 


In CGA color graphics modes, you can use the _ selectpalette routine to choose 
one of several predefined palettes. 


On EGA, MCGA, VGA, and SVGA video systems, you can “remap” (change) the 
palette using the _remappalette or _ remapallpalette routines. For instance, the 
EGA _ERESCOLOR mode offers a total of 64 color values, of which 16 can be 
displayed at a time. In this mode, the palette contains 16 “color indices,” or slots to 
which you can assign color values. 


The _remappalette routine changes a single color index to a specified color 
value. The _ remapallpalette routine changes all of the available palette entries 
simultaneously. 


Setting Attributes 


The low-level output functions that draw lines, arcs, ellipses, and other basic 
figures do not specify color or line-style information. Instead, the low-level 
graphics functions rely on a set of attributes that are set independently by the 
following functions: 


Routine Use 

_getarcinfo Determines the endpoints in viewport coordinates of the most 
recently drawn arc or pie 

_getcolor Gets the current color 

_ getfillmask Gets the current fill mask 

_ getlinestyle Gets the current line-style mask 

_getwritemode Gets the current logical write mode 

_setcolor Sets the current color 

_ Setfillmask Sets the current fill mask 

_Setlinestyle Sets the current line-style mask 


_setwritemode Sets logical write mode for line drawing 
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The _ getcolor and _setcolor functions get or set the current color index for 
graphics and font output. The _ getbkcolor and _ setbkcolor functions get or set 
the current background color. (The _ getbkcolor and _ setbkcolor functions are 
listed in “Configuring Mode and Environment” on page 22.) 


The _ getfillmask and _ setfillmask functions get or set the current fill mask. The 
mask is an 8-by-8-bit template array, with each bit representing a pixel. If a bit is 
0, the pixel in memory is left untouched, as the mask is transparent to that pixel. If 
a bit is 1, the pixel is assigned the current color value. The template is repeated as 
necessary over the entire fill area. 


The _ getlinestyle and _setlinestyle functions get or set the current line style. The 
line style is determined by a 16-bit template buffer with each bit corresponding to 
a pixel. If a bit is 1, the pixel is set to the current color. If a bit is 0, the pixel is not 
changed. The template is repeated for the length of the line. 


The _ getwritemode and _ setwritemode functions get or set the logical write 
mode for straight-line drawing. The default mode, _GPSET, causes lines to be 
drawn in the current graphics color. Other modes combine the current graphics 
color and the original screen image using various logical operations. 


Creating Graphics Output 


The graphics output functions use a set of specified coordinates and draw various 
figures. They use the current or default attributes for line-style mask, fill mask, 
write mode, background color, and foreground color. 


The name of each function announces its task or the figure it draws, as the 


following list indicates: 


Routine 


_arc, _arc_Ww, _arc_Wwxy 


_ ellipse, _ ellipse_ w, 
_ellipse_ wxy 


_ floodfill, _ floodfill_ w 


_ getcurrentposition, 
_ getcurrentposition_ w 


_ getpixel, _ getpixel_w 
_lineto, _ lineto_w 


_moveto, _moveto_w 
_ pie, _ pie_w, —_ pie_ wxy 


_ polygon, _ polygon_w, 
_ polygon_wxy 


Use 


Draw an arc 
Draw an ellipse or circle 


Flood-fill an area of the screen with the current color 


Obtain the current graphic-output position used by 
_lineto and _ outgtext 


Obtain a pixel’s color 

Draw a line from the current graphic-output position to a 
specified point | 

Move the current graphic-output position to a specified 
point 

Draw a pie-slice-shaped figure 

Draw or scan-fill a polygon 
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Routine Use 


_rectangle, Draw or scan-fill a rectangle 
_rectangle_w, 
_rectangle_wxy 


_setpixel, _setpixel_ w Set a pixel’s color 


Most of these routines are available in several forms, which are indicated by their 
names. Output functions without a suffix use the view coordinate system. Func- 
tions that end with _ w take double values as arguments and use the window 
coordinate system. Functions that end with _ wxy use _ wxycoord structures to 
define the coordinates and use the window coordinate system. 


Circular figures, such as arcs and ellipses, are centered within a “bounding rec- 
tangle” specified by two points that define the diagonally opposed corners of the 
rectangle. The center of the rectangle becomes the center of the figure, and the 
rectangle’s borders determine the size of the figure. 


Creating Text Output 


The next group of routines provides text output in both graphics and text modes. 
Unlike the standard console I/O library routines, these functions recognize text- 
window boundaries and use the current text color. 


Routine Use 

_displaycursor Sets the cursor on or off upon exit from a graphics routine 
_ gettextcolor Obtains the current text color 

_ gettextcursor Returns the current cursor attribute (text modes only) 

_ gettextposition Obtains the current text-output position 

_gettextwindow Gets the current text window boundaries 

_outmem Prints text of a specified length from a memory buffer 

_ outtext Outputs a text string to the screen at the current text position 
_scrolltextwindow = Scrolls the current text window up or down 

_Settextcolor Sets the current text color 

_settextcursor Sets the current cursor attribute (text modes only) 
_settextposition Relocates the current text position 

_Settextwindow Defines the current text-display window 

_wrapon Enables or disables line wrap 


The _outtext and _outmem routines provide no formatting. If you want to output 
integer or floating-point values, you must convert the values into a string variable 
(using the sprintf function) before calling these routines. 
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The _ outtext routine recognizes the \n (newline character) and \r (carriage return) 
sequences. The _outmem routine treats these sequences as printable graphics 
characters. 


Transferring Images 


The functions in this category transfer screen images between memory and the dis- 
play, using a buffer allocated by the application, or determine the size in bytes of 
the buffer needed to store a given image. 


The functions that end with _w or _ wxy use window coordinates; the other func- 
tions in this set use view coordinates. 


Routine Use 


_ getimage, Store a screen image in memory 

_ getimage_w, 

_ getimage_wxy 

_imagesize, Return the size (in bytes) of the buffer needed to store the 
_imagesize_w, image 

_imagesize_wxy | 


_ putimage, Retrieve an image from memory and display it 
_putimage_w 


In some cases, the buffer needed to store an image with the _ getimage functions 
must be larger than 64K (65,534) bytes. Use the _halloc routine to allocate a 


buffer larger than 64K. 

Displaying Fonts 

The functions listed in this section control the display of font-based characters on 

the screen. 

Routine Use 

_ getfontinfo Obtains the current font characteristics 

_ getgtextextent Determines the width in pixels of specified text in the current © 
font 

_ getgtextvector Gets orientation of font text output 

_outgtext Outputs text in the current font to the screen at the specified 
pixel position 

_registerfonts Initializes font library 

_ setfont Finds a single font that matches a specified set of characteristics 


and makes this font the current font for use by the _ outgtext 
function 
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Routine Use 
_Setgtextvector Sets the current orientation for font text output 
_ungisterfonts Frees memory allocated by _registerfonts 


Presentation-Graphics Functions 


The presentation-graphics functions are declared in the P@CHART.H include file. 
The library can be divided into the three categories listed below, corresponding to 
the different tasks involved in creating and manipulating graphic objects: 


Category Task 


Displaying presentation graphics Initializes video structures for presentation 
graphics and establishes the default chart 
type. Displays presentation-graphics chart: 
bar, column, pie, scatter, or line chart. 

Analyzing presentation-graphics data § Analyzes data (does not display chart). 


Manipulating presentation-graphics Modifies basic chart structures (e.g., palettes, 
structures cross-hatching styles). 


Displaying Presentation Graphics 


The functions listed in this section initialize the presentation-graphics library and 
display the specified graph type. 


Because the _ pg_initchart routine initializes the presentation-graphics library, it 
must be called before any other function in the presentation-graphics library. The 
_pg_defaultchart function initializes the variables in the chart environment. 


The other routines in this category display the specified graph. The single-series 
versions plot one set of data, and the multiseries versions (those ending with an ms 
suffix) plot several sets of data in the same chart style. 


Presentation-graphics programs can display text in different font sizes by taking 
advantage of font-based characters (see the previous section, “Displaying Fonts’). 
Call the _registerfonts and _ setfont routines to select a font before calling the 

_ pg_initchart routine. Subsequent charts use the selected font. You can later call 
the _unregisterfonts routine to restore the default character font and free the 
memory previously allocated for fonts. 


Note If your program uses the alternate math package—if it is compiled with 
/FPa—it cannot use the PGCHART.LIB module. 
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Routine Use 

_pg_chart Displays a single-series bar, column, or line chart 

_pg_chartms Displays a multiseries bar, column, or line chart 

_pg_chartpie Displays a pie chart 

_pg_chartscatter Displays a scatter diagram for a single series of data 

_pg_chartscatterms Displays a scatter diagram for more than one series of data 

_ pg_ defaultchart Initializes all necessary variables in the chart environment for 
a specified chart type 

_pg_initchart Initializes the presentation-graphics library 


Analyzing Presentation-Graphics Charts 


These routines calculate default values for the specified graph type but do not dis- 
play the chart. The single-series versions analyze one set of data, and the multi- 
Series versions analyze several sets of data in the same chart style. 


Routine Use 

_ pg_analyzechart Analyzes a single series of data for a bar, column, or line 
chart 

_ pg_analyzechartms Analyzes a multiseries of data for a bar, column, or line 
chart 

_pg_analyzepie Analyzes data for a pie chart 

_pg_analyzescatter Analyzes a single series of data for a scatter diagram 


_pg_analyzescatterms Analyzes a multiseries of data for a scatter diagram 


Manipulating Presentation-Graphics Structures 
These functions control low-level aspects of the presentation-graphics package. 


Routine Use 
_pg_ getchardef Retrieves the current 8-by-8-p1xel bit map for a specified 
character 


_pg_getpalette Retrieves current colors, line styles, fill patterns, and plot 
characters for all presentation-graphics palettes 


_pg_getstyleset Retrieves the contents of the current styleset 
_ pg_hlabelchart Writes text horizontally on the screen 


_pg_resetpalette Sets current colors, line styles, fill patterns, and plot characters 
to the default values for the current screen mode 


__pg_resetstyleset Resets the contents of the current styleset to the default value for 
the current screen mode 


_pg_setchardef Sets the 8-by-8-pixel bit map for a specified character 
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Routine Use 

_pg_setpalette Sets current colors 

_pg_setstyleset Sets the contents of the current styleset 
_pg_vlabelchart Writes text vertically on the screen 


2.7 Input and Output 


The input and output (I/O) routines allow you to read and write data to and from 
files and devices. In C, there are no predefined file structures; all data items are 
treated as sequences of bytes. The following three types of I/O functions are 
available: 


= Stream 
= Low-level 


=" Console and port 


The stream I/O functions treat data as a stream of individual characters. By 
choosing among the many stream functions available, you can process data in 
different sizes and formats, from single characters to large data structures. Stream 
I/O also provides buffering, which can significantly improve performance. 


The low-level I/O routines do not perform buffering and formatting. Instead, they 
invoke the operating system’s input and output capabilities directly. These 
routines let you access files and peripheral devices at a more basic level than the 
stream functions. 


The console and port I/O routines allow you to read or write directly to a console 
(keyboard and screen) or an I/O port (such as a printer port). The port I/O routines 
simply read and write data in bytes. With console I/O routines, some additional 
options are available, such as detecting whether a character has been typed at the 
console. You can also choose between echoing characters to the screen as they are 
read or reading characters without echoing. 


The run-time library also provides a number of direct DOS I/O system-call 
routines. These are described in “System Calls” on page 55. 


You can perform file I/O operations in two modes: text and binary. The following 
section describes these modes and their use. You can also ensure that the fflush 
and _ flushall routines write data to storage media rather than to just the operating 
system’s buffers. See “Stream Routines” on page 33. 
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Warning! Because stream routines are buffered and low-level routines are not, the 
two types of routines are generally incompatible. You should use either stream or 
low-level routines consistently for processing a given file. 


Text and Binary Modes 


Many C and C++ programs use data files for input and output. With DOS, data 
files are normally processed in text mode. In this mode, each carriage-return— 
line-feed (CR-LF) combination is translated into a single line-feed character 
during input. During output, each line-feed character is translated into a CR-LF 
combination. 


Sometimes you may want to process a file without making those translations. In 
these cases you use binary mode, which suppresses CR-LF translations. 


You can control the file translation mode in the following ways: 


= To process a few selected files in binary mode, while retaining the default text 
mode for most files, you can specify binary mode when you open the selected 
files. The fopen routine opens a file in binary mode when you specify the letter 
b in the access-mode string for the file. The _ open routine opens a file in bi- 
nary mode when you specify the O_ BINARY flag in the oflag argument. For 
more information about fopen and _ open, see the reference description of each 
routine. 


= To process most or all files in binary mode, you can change the default mode to 
binary. The global variable _fmode controls the default translation mode, 
which is normally text. If you set _fmode to _O_ BINARY, the default mode 
is binary except for stdaux and stdprn, which are opened in binary mode by 
default. 


You can change the value of _fmode in two ways: 


= Link with the file BINMODE.OBJ (supplied with Microsoft C/C++). This 
changes the initial setting of _fmode to the _O_ BINARY flag, causing all 
files except stdin, stdout, and stderr to be opened in binary mode. 


= Change the value of _fmode directly by setting it to the O_ BINARY flag in 
your program. This has the same effect as linking with BINMODE.OBJ. 


You can still override the default mode (now binary) for a particular file by 
opening it in text mode. Specify the letter t when using fopen, or specify the 
_O_ TEXT flag when using _ open. 


By default, the stdin, stdout, and stderr files are opened in text mode, and the 
stdaux and stdprn files are opened in binary mode. The _setmode routine allows 
you to change these defaults or change the mode of a file after it has been opened. 
See the reference description of _setmode for details. 
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Stream Routines 


Stream I/O functions handle data as a continuous stream of characters. To use the 
stream functions, you must include the file STDIO.H in your program. This file de- 
fines constants, types, and structures used in the stream functions, and contains 
function declarations and macro definitions for the stream routines. 


When a file is opened for I/O using the stream functions, the opened file is as- 
sociated with a structure of type FILE (defined in STDIO.H) containing basic in- 
formation about the file. A pointer to the FILE structure is returned when the 
stream is opened. Subsequent operations use this pointer (also called the “stream 
pointer,” or just “stream’’) to refer to the file. 


The stream functions provide for buffered, formatted, or unformatted input and 
output. When a stream is buffered, data that is read from or written to the stream is 
collected in an intermediate storage location called a “buffer.” In write operations, 
the output buffer’s contents are written to the appropriate final location when the 
buffer is full, the stream is closed, or the program terminates normally. The buffer 
is said to be “‘flushed’’ when this occurs. In read operations, a block of data is 
placed in the input buffer. When the input buffer is empty, the next block of data is 
transferred into the buffer. 


Buffering produces efficient I/O because the system can transfer a large block of 
data in a single operation rather than performing an I/O operation each time a data 
item is read from or written to a stream. However, if a program terminates abnor- 
mally, output buffers may not be flushed, resulting in loss of data. 


You can use the fflush and _ flushall routines to ensure that the buffer associated 
with the specified file or all of the open buffers are flushed to the operating sys- 
tem. If a file was opened with fopen or _ fdopen and the c flag, or if the program 
is linked with COMMODE.OBJ, the contents of a flushed buffer are written to 
disk. 


Some of the constants defined in STDIO.H may be useful in your program. The 
manifest constant EOF is defined to be the value returned at end-of-file. NULL is 
the null pointer. FILE is the structure that maintains information about a stream. 
BUFSIZ defines the default size of stream buffers, in bytes. 


Routine Use 

clearerr Clears the error indicator for a stream 

{close Closes a stream 

_fcloseall Closes all open streams 

_fdopen Associates a stream with an open file handle 
feof Tests for end-of-file on a stream 

ferror Tests for error on a stream 


fflush Flushes a stream 
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Routine 


fgetc 
_fgetchar 
fgetpos 
fgets 
_fileno 
_flushall 
fopen 
fprintf 
fputc 
_fputchar 
fputs 
fread 
freopen 
fscanf 
fseek 
fsetpos 
_fsopen 
ftell 
fwrite 
getc 
getchar 
gets 
_getw 
printf 
putc 
putchar 
puts 
_putw 
rewind 
_rmtmp 
scanf 
setbuf 
setvbuf 
_snprintf 
sprintf 
sscanf 


Use 


Reads a character from a stream (function version) 
Reads a character from stdin (function version) 
Gets the position indicator of a stream 

Reads a string from a stream 

Gets the file handle associated with a stream 
Flushes all streams 

Opens a stream 

Writes formatted data to a stream 

Writes a character to a stream (function version) 
Writes a character to stdout (function version) 
Writes a string to a stream 

Reads unformatted data from a stream 
Reassigns a FILE pointer to a new file 

Reads formatted data from a stream 

Moves file position to a given location 

Sets the position indicator of a stream 

Opens a stream with file sharing 

Gets current file position 

Writes unformatted data items to a stream 
Reads a character from a stream 

Reads a character from stdin 

Reads a line from stdin 

Reads a binary int item from a stream 

Writes formatted data to stdout 

Writes a character to a stream 

Writes a character to stdout 

Writes a line to a stream 

Writes a binary int item to a stream 

Moves file position to beginning of a stream 
Removes temporary files created by tmpfile 
Reads formatted data from stdin 

Controls stream buffering 

Controls stream buffering and buffer size 
Writes formatted data of a specified length to a string 
Writes formatted data to a string 

Reads formatted data from a string 
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Routine Use 

_tempnam Generates a temporary filename in given directory 
tmpfile Creates a temporary file 

tmpnam Generates a temporary filename 

ungetc Places a character in the buffer 

viprintf Writes formatted data to a stream 

vprintf Writes formatted data to stdout 

_vsnprintf Writes formatted data of a specified length to a string 
vsprintf Writes formatted data to a string 


Opening a Stream 


A stream must be opened using the _fdopen, fopen, freopen, or _ fsopen function 
before input and output can be performed on that stream. When opening a stream, 
the named stream can be opened for reading, writing, or both, and it can be opened 
in either text or binary mode. 


The _fdopen, fopen, freopen, and _ fsopen functions return a FILE pointer. You 
normally assign the pointer value to a variable and use the variable to refer to the 
opened stream. For instance, if your program contains the lines 


FILE *infile 
infile = fopen ("test.dat", "r"); 


you can use the FILE pointer variable infile to refer to the stream. 


Using Predefined Stream Pointers 


When a program begins execution, the startup code automatically opens several 
streams: standard input, standard output, and standard error. By default, the stand- 
ard input, standard output, and standard error streams are directed to the console 
(keyboard and screen). This means that when a program expects input from the 
“standard input,” it receives that input from the console. Similarly, a program that 
writes to the “standard output” prints its data to the console. Error messages 
generated by the library routines are sent to the “standard error,” meaning that 
error messages appear on the user’s console. 


With DOS, two additional streams are opened: standard auxiliary and standard 
print. The assignment of standard auxiliary and standard print depends on the ma- 
chine configuration. These streams usually refer to the first serial port and a printer 
port, but those ports may not be available on some systems. Be sure to check your 
machine configuration before using these streams. 
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You can refer to the standard streams with the following predefined stream 
pointers: 


Pointer Stream 

stdin Standard input 

stdout Standard output 

stderr Standard error 

stdaux Standard auxiliary (DOS only) 
stdprn Standard print (DOS only) 


You can use these pointers in any function that requires a stream pointer as an ar- 
gument. Some functions, such as getchar and putchar, are designed to use stdin 
or stdout automatically. The pointers stdin, stdout, stderr, stdaux, and stdprn 

are constants, not variables; do not try to assign them a new stream pointer value. 


DOS allows you to redirect a program’s standard input and standard output at the 
operating-system command level. See your operating-system user’s manual for a 
complete discussion of redirection. 


Within your program, you can use freopen to redirect stdin, stdout, stderr, 
stdaux, or stdprn so that it refers to a disk file or to a device. See the reference 
description of freopen for more details. 


Controlling Stream Buffering 


As mentioned earlier, stream routines can use in-memory buffers to speed I/O 
operations. Files opened using the stream routines are buffered by default, except 
for stdaux and stdprn, which are normally unbuffered. The stdout and stderr 
streams are flushed whenever they are full or (if you are writing to a character 
device) after each library call. 


By using the setbuf or setvbuf function, you can cause a stream to be unbuffered, 
or you can associate a buffer with an unbuffered stream. Buffers allocated by the 
system are not accessible to you, but buffers allocated with setbuf or setvbuf refer 
to arrays in your program and can be manipulated. Buffers can be any size up to 
INT_ MAX bytes. This size is set by the manifest constant BUFSIZ in STDIO.H 
if you use seftbuf; if you use setvbuf, you can set the size of the buffer yourself. 
(See the descriptions of setbuf and setvbuf in the reference section for more 
details.) 


Note These routines affect only buffers created by the run-time library routines. 
They have no effect on buffers created by the operating system. 
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Committing Buffer Contents to Disk 


Normally, both the fflush and the _ flushall functions pass the contents of a pro- 
gram buffer to the operating system, which can cache data before writing it to 
disk. In the case of a system failure, data cached by the operating system will be 
lost. The commit-to-disk feature ensures that the flushed contents of a buffer are 
written to storage media. 


There are two ways to commit buffer contents to disk: 


= Link with the file COMMODE.OB] (provided with Microsoft C/C++) to set a 
global commit flag. The default setting of the global flag is “no-commit.” 


= Set the c “commit” flag with fopen or _fdopen to open the file in commit 
mode. The n flag specifies the “no-commit” mode. 


COMMODE.OB]J allows existing code to use the commit feature. Any file 
specifically opened with either the c or the n flag will behave according to the 
flag, regardless of the state of the global commit/no-commit flag. Thus, some files 
can be opened with committing contents to disk and some without. 


Closing Streams 


The fclose and _ fcloseall functions close a stream or streams. The fclose routine 
closes a single specified stream; _ fcloseall closes all open streams except stdin, 
stdout, stderr, stdaux, and stdprn. If your program does not explicitly close a 
stream, the stream is automatically closed when the program terminates. How- 
ever, it is a good practice to close a stream when your program is finished with it, 
as the number of streams that can be open at a given time is limited. 


Reading and Writing Data 


The stream functions allow you to transfer data in a variety of ways. You can read 
and write binary data (a sequence of bytes), or specify reading and writing by 
characters, lines, or more complicated formats. 


Reading and writing operations on streams always begin at the current position of 
the stream, known as the “file pointer” for the stream. The file pointer is changed 
to reflect the new position after a read or write operation takes place. For example, 
if you read a single character from a stream, the file pointer is increased by one 
byte so that the next operation begins with the first unread character. If a stream is 
opened for appending, the file pointer is automatically positioned at the end of the 
file before each write operation. 
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When switching directly between output and input, there must be an intervening 
call to the fflush function or to a file-positioning function (fseek, fsetpos, or 
rewind). Input can be directly followed by output without an intervening call to a 
file-positioning function if the input operation encounters end-of-file. 


The fseek and fsetpos functions allow you to position the file pointer anywhere in 
a file. The next operation occurs at the position you specified. The rewind routine 
positions the file pointer at the beginning of the file. Use the ftell or fgetpos 
routine to determine the current position of the file pointer. 


The feof macro detects an end-of-file condition on a stream. Once the end-of-file 
indicator is set, it remains set until the file is closed, or until clearerr, fseek, 
fsetpos, or rewind is called. 


Streams associated with a character-oriented device (such as a console) do not 
have file pointers. Data coming from or going to a console cannot be accessed ran- 
domly. Routines that set or get the file-pointer position (such as fseek, fgetpos, 
fsetpos, ftell, or rewind) have undefined results if used on a stream associated 
with a character-oriented device. 


Detecting Errors 


When an error occurs in a stream operation, an error indicator for the stream is set. 
You can use the ferror macro to test the error indicator and determine whether an 
error has occurred. Once an error has occurred, the error indicator for the stream 
remains set until the stream is closed, or until you explicitly clear the error indica- 
tor by calling clearerr or rewind. 


Low-Level Routines 


Low-level input and output calls do not buffer or format data. Declarations for the 
low-level functions are given in the include files IO.H, FCNTL.H, SYS\TYPES.H, 
and SYS\STAT.H. Unlike the stream functions, low-level functions do not require 
the include file STDIO.H. However, some common constants are defined in 
STDIO.H; for example, the end-of-file indicator (EOF) may be useful. If your 
program requires these constants, you must include STDIO.H. 


Routine Use 

_ close Closes a file 

_commit Flushes a file to disk 

_creat Creates a file | 
_dup Creates a second handle for a file 
_dup2 Reassigns a handle to a file 


_ eof Tests for end-of-file 
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Routine Use 

_iseek Repositions file pointer to a given location 
_open Opens a file 

_read Reads data from a file 

_sopen Opens a file for file sharing 

_ tell Gets current file-pointer position 

_umask Sets default file-permission mask 

_write Writes data to a file 

Opening a File 


You must open a file before performing I/O functions on it. The _ open function 
opens a file; it can also create the file when opening it. With DOS versions 3.0 and 
later, you can use _sopen to open a file with file-sharing attributes. The _ creat 
function can create and open a file. 


The file can be opened for reading, writing, or both, and opened in either text or bi- 
nary mode (see “Text and Binary Modes” on page 32). The include file FCNTL.H 
must be included when opening a file, as it contains definitions for flags used in 
_open. In some cases, the files SYS\TYPES.H and SYS\STAT.H must also be in- 
cluded; for more information, see the reference description for the _ open function. 


These functions return a file handle, which is normally assigned to an integer 
variable. You use the variable to refer to the opened file. 


Reading and Writing Data 


Use the _read and _ write routines to read and write to files. These operations 
begin at the current position in the file. The current position is updated each time a 
read or write operation occurs. 


The _Iseek function allows you to place the file pointer anywhere in the file. The 
next operation occurs at the position you specified. The _ tell function indicates 
the current position of the file pointer. The _ eof routine tests for the end of the file. 


Low-level I/O routines set the errno variable when an error occurs. Chapter 3, 
“Global Variables and Standard Types,” describes errno. 


Character-oriented devices, such as the console, do not have file pointers. The 
_Iseek and _ tell routines have undefined results if used on a handle associated 
with a device. 
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Closing Files 


The _ close function closes an open file. Open files are automatically closed when 
a program terminates. However, it is a good practice to close a file when your pro- 
gram is finished with it, as there is a limit to the number of files that can be open at 
one time. 


Using Predefined Handles 


When a program begins execution, five files are automatically opened: standard 
input, standard output, standard error, standard auxiliary, and standard print. 


Low-level routines can access these files using the following predefined handles: 


Stream Handle 
stdin 0 
stdout 1 
stderr 2 
stdaux (DOS only) 3 
stdprn (DOS only) 4 


You can use these file handles without previously opening the files. The files are 
opened and the handles are assigned when the program starts. 


The _dup and _ dup2 functions allow you to assign multiple handles for the same 
file. These functions are typically used to associate the predefined file handles 
with different files. 


With DOS and Windows, you can redirect the standard input and standard output 
at the operating-system command level. See your operating-system user’s manual 
for a complete discussion of redirection. 


Increasing the Maximum Number of File Handles and Streams 


You can change the maximum number of file handles and streams that your pro- 
gram can handle. The process is simple and involves changing some constants in 
the startup source files, which are provided with Microsoft C/C++, and then com- 
piling and linking the new startup code with your program. The following sections 
describe the process. 
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Increasing File Handles 


DOS, Windows, and Quick Win use the value of the constant _NFILE_ to establish 
the maximum number of available file handles. To increase the number of file han- 
dles, edit the startup source file CRTODAT.ASM and change the line 


_NFILE. = 20 


so that _NFILE_ is set to the desired maximum. For example, to increase the maxi- 
mum number of available file handles to 40, change the line as shown here: 


_NFILE_ = 4@ 


CRTODAT.ASM contains a section of conditional code that is automatically 
enabled when you change the value of _NFILE_. 


QuickWin uses the constant _WFILE_ to establish the maximum number of availa- 
ble text child windows. You can edit CRTODAT.ASM to change _WFILE_. 
Change the line 


_WFILE_ = 20 


so that _WFILE_ is set to the desired maximum. For example, to increase the maxi- 
mum number of available text child windows to 40, change the line as shown here: 


_WFILE_ = 40 


Note Increasing the number of file handles allows you to use low-level I/O func- 
tions, such as _open and _ read, with more files. However, it does not affect the 
number of stream-level I/O files (that is, the number of FILE * streams). 


Increasing Streams 


To increase the maximum number of streams, edit one or more of the following 
source files and constants: 


System Source File Constant 
DOS _FILE.C _NFILE_ 
Windows and QuickWin FILE.ASM _NFILE_ 


Quick Win WFILE.ASM _WFILE_ 
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For DOS, Windows, and QuickWin, change the line 


_NFILE_ equ 20 


to set _NFILE_ to the desired maximum. For example, to allow a maximum of 40 
streams, change the line as shown here: 


_NFILE_ equ 4@ 


In addition, you can change the value of the constant _WFILE_, found in 
WFILE.ASM, to increase the maximum number of available Quick Win text child 
windows. 


Increasing the number of streams allows you to use stream-level I/O functions, 
such as fopen and fread, with more files. 


Note The number of low-level file handles must be greater than or equal to the 
number of stream-level files. For example, if you increase the value of _NFILE_ 
in the module _FILE.C, you must also increase the value of _NFILE_ in the mod- 
ule CRTODAT.ASM. Similarly, if you increase the value of _WFILE_ in the mod- 
ule WFILE.ASM, you must also increase the value of _WFILE_ in the module 
CRTODAT.ASM. 


Increasing the System Limit 


To use more than 20 files at a time, you must increase the file limit imposed on 
your process by the operating system. 


To increase the system-wide limit, increase the number of files available on your 
system as a whole by editing your system configuration file (CONFIG.SYS). For 
example, to allow 50 open files at a time on your system, put this statement in the 
configuration file: 


FILES=5@ 


Using the Modified Startup Files 


After you modify one or more of the startup source files, you need to recompile 
the file(s) using the batch file CSTARTUP.BAT. Be sure to read the file 
README.TXT, which is located in the same directory as CSTARTUP.BAT, 
before running the batch file. 


To use a new object file, either explicitly link your program with it or replace it in 
the appropriate model of the run-time library. For example, after you assemble 
CRTODAT.ASM, the object file will be CRTODAT.OBJ. 
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Console and Port I/O 


The console and port I/O routines are implemented as functions and are declared 
in the include file CONIO.H. These functions perform reading and writing opera- 
tions on your console or on the specified port. The _ cgets, _ cscanf, _ getch, 
_getche, and _ kbhit routines take input from the console, while _ cprintf, 
_cputs, _ putch, and _ ungetch write to the console. The input or output of these 
functions can be redirected. 


Routine Use 

_cgets Reads a string from the console 

_ceprintf Writes formatted data to the console 

_cputs Writes a string to the console 

_cscanf Reads formatted data from the console 

_getch Reads a character from the console 

_getche Reads a character from the console and echoes it 
_inp Reads one byte from the specified I/O port 

_inpw Reads a two-byte word from the specified I/O port 
_kbhit Checks for a keystroke at the console 

_outp Writes one byte to the specified I/O port 

_outpw Writes a two-byte word to the specified I/O port 
_putch Writes a character to the console 

_ungetch “Ungets” the last character read from the console so that it becomes 


the next character read 


Note Programs that need only run under DOS can also use a number of direct 
DOS I/O system calls (__dos_ open, _ dos_ read, _ dos_close, etc.). These are 
described in detail in “System Calls” on page 55. 


The console or port does not have to be opened or closed before I/O is performed, 
so there are no open or close routines in this category. The port I/O routines _inp 
and _ outp read or write one byte at a time from the specified port. The _inpw and 
_outpw routines read and write two-byte words, respectively. 


The console I/O routines allow reading and writing of strings (_cgets and 
_cputs), formatted data (_cscanf and _cprintf), and characters. Several options 
are available when reading and writing characters. 


The _ putch routine writes a single character to the console. The _ getch and 
_ getche routines read a single character from the console: _ getche echoes the 
character back to the console, while _ getch does not. The _ ungetch routine 
“ungets” the last character read; the next read operation on the console begins 
with the “ungotten” character. 
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The _kbhit routine determines whether a Key has been struck at the console. This 
routine allows you to test for keyboard input before you attempt to read from the 
console. 


Note The console I/O routines are not compatible with stream or low-level library 
routines and should not be used with them. 


2.8 Internationalization 


2.9 Math 


Internationalization routines are useful for creating different versions of a 
program for international markets. These routines are declared in the header file 
LOCALE.H, except for strftime, which is declared in TIME.H. 


Routine Use 

localeconv Sets a structure with appropriate values for formatting numeric 
quantities 

setlocale Selects the appropriate locale for the program 

strcoll Compares strings using locale-specific information 

strftime Formats a date and time string 

strxfrm Transforms a string based on locale-specific information 


Currently only the "C" locale is supported by Microsoft C/C++. 


The math routines allow you to perform common mathematical calculations. All 
math routines work with floating-point values and therefore require floating-point 
support (see “Floating-Point Support” on page 14). 


The math library provides two versions of some routines. The first version of the 
routine supports double arguments and return values. The second version supports 
an 80-bit data type, allowing the routine to take long double arguments and return 
a long double value. The second version usually has the same name with the suf- 
fix l. For instance, the acos routine supports double arguments and return values, 
while _acosl supports long double arguments and return values. 


Routines which support long double values are not available when you compile 
with the /FPa (alternate math) compiler option. The same is true of the _ clear87, 
_control87, and _ status87 routines. 
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Most math declarations are in the include file MATH.H. However, the _ clear87, 
_control87, _ fpreset, and _ status87 routines are defined in FLOAT.H; the abs 
and labs functions are defined in MATH.H and STDLIB.H; and the div and Idiv 
routines are declared in STDLIB.H. 


Routine 


acos, _ acosl 
asin, _ asinl 
atan, _ atanl 
atan2, _ atan2I 
Bessel 

_cabs, _ cabsl 
ceil, _ ceill 
_clear87 
_control87 


cos, _cosl 
cosh, _ coshl 
_ dieeetomsbin 


div 
_dmsbintoieee 


exp, _ expl 
fabs, _ fabsl 
_fieeetomsbin 


floor, _ floor! 
fmod, _fmodl 
_fmsbintoieee 


_fpreset 

frexp, _frexpl 
_hypot, _ hypotl 
Idexp, _ Idexpl 
Idiv 


log, _logl 
log10, _ log101 
_Irotl, _lrotr 


Use 


Calculate the arccosine 

Calculate the arcsine 

Calculate the arctangent 

Calculate the arctangent 

Calculates Bessel functions 

Find the absolute value of a complex number 
Find the integer ceiling 

Gets and clears the floating-point status word 


Gets the old floating-point control word and sets a new control- 
word value 


Calculate the cosine 
Calculate the hyperbolic cosine 


Converts IEEE double-precision number to Microsoft (MS) 
binary format 


Divides one integer by another, returning the quotient and 
remainder 


Converts Microsoft binary double-precision number to IEEE 
format 


Calculate the exponential function 
Find the absolute value 


Converts IEEE single-precision number to Microsoft binary 
format 


Find the largest integer less than or equal to the argument 
Find the floating-point remainder 


Converts Microsoft binary single-precision number to IEEE 
format 


Reinitializes the floating-point-math package 
Calculate an exponential value 

Calculate the hypotenuse of a right triangle 
Calculate the product of the argument and 2¢p 


Divides one long integer by another, returning the quotient and 
remainder 


Calculate the natural logarithm 
Calculate the base-10 logarithm 
Shift an unsigned long int item left ( _Irotl) or right ( _Irotr) 
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Routine 
_matherr, 
_matherr!l 
__max, __ min 
modf, _ modfl 
pow, _ powl 
rand 

_rotl, _rotr 
sin, _ sinl 
sinh, _ sinhl 
sqrt, _sqrtl 
srand 

_ Status87 
tan, _ tanl 
tanh, _ tanhl 


Use 


Handle math errors 


Return the larger or smaller of two values 

Split the argument into integer and fractional parts 
Calculate a value raised to a power 

Gets a pseudorandom number 

Shift an unsigned int item left ( _rotl) or right (__rotr) 
Calculate the sine 

Calculate the hyperbolic sine 

Find the square root 

Initializes a pseudorandom series 

Gets the floating-point status word 

Calculate the tangent 

Calculate the hyperbolic tangent 


The Bessel routine does not correspond to a single function, but to 12 functions 
named _j0, _j1, _jn, _y0, _yl1, _yn, _jOl, _j1l, _jnl, _yOl, _ y1l, and _ ynl. 


The _matherr and _ matherrl routines are invoked by the math functions when 
errors occur. The _matherr routine handles functions that return a double value, 
and _matherrl handles routines that return a long double. 


These routines are defined in the library, but you can redefine them for different 
error handling. The user-defined function, if given, must follow the rules given in 
the reference description of _matherr and _ matherrl. 


You are not required to supply a definition for the _ matherr routines. If no defini- 
tion is present, the default error returns for each routine are used. The reference 
description of each routine describes that routine’s error returns. 


2.10 Memory Allocation 


The memory-allocation routines allow you to allocate, free, and reallocate 
blocks of memory. Memory-allocation routines are declared in the include file 
MALLOC.H. The C++ _set_new_handler functions allow you to redefine the 
action of the C++ new operator and are declared in include file NEW.H. 


Routine 


_alloca 


_bfreeseg 

_bheapseg 

calloc, _bealloc, _ fcalloc, _ ncalloc 
_expand, _ bexpand, _fexpand, _ nexpand 


free, _bfree, _ ffree, _ free 
_freect 


_halloc 
_heapadd, _ bheapadd 


_heapchk, _ bheapchk, _ fheapchk, 
_nheapchk 


_heapmin, _ bheapmin, 
_fheapmin, _ nheapmin 


_heapset, _ bheapset, _ fheapset, _nheapset 


_heapwalk, _ bheapwalk, _ fheapwalk, 
_nheapwalk 


_hfree 
malloc, _bmalloc, _fmalloc, _ nmalloc 
_memavl 


_memmax 


_msize, _bmsize, _ fmsize, _nmsize 
realloc, _brealloc, _ frealloc, _ nrealloc 


_set_new_ handler, _ set_ bnew_ handler, 
_set_fnew_ handler, _ set_ hnew_handler, 
_set_nnew_ handler 


_Stackavail 
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Use 

Allocates a block of memory from 
the program’s stack 

Frees a based heap 

Allocates a based heap 

Allocate storage for an array 


Expand or shrink a block of memory 
without moving its location 


Free an allocated block 


Returns approximate number of items 
of given size that could be allocated 
in the near heap 


Allocates storage for huge array 
Add memory to a heap 
Check a heap for consistency 


Release unused memory in a heap 


Fill free heap entries with a specified 
value 


Return information about each entry 
in a heap 


Frees a block allocated by _ halloc 
Allocate a block of memory 


Returns approximate number of bytes 
available for allocation in the near 
heap 


Returns size of largest contiguous 
free block in the near heap 


Return size of an allocated block 
Reallocate a block to a new size 
Enable an error-handling mechanism 


Returns size of stack space available 
for allocation with _alloca 
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Some memory-management routines, such as malloc, are available in different 
versions that begin with _b, _f, or __n. These variations are described in the 
following section. 


The malloc and free routines allocate and free memory space, respectively, while 
a program runs. The malloc routine allocates memory from the “heap,” which is 
a pool of memory not otherwise used by your program. In tiny-, small-, and 
medium-model programs, the heap consists of unused memory in your program’s 
default data segment. In compact-, large-, and huge-model programs, it is unused 
memory outside the default data segment. 


The malloc and free routines satisfy the memory-allocation requirements of most 
programs. More specialized memory-management routines are discussed below. 


The realloc and _ expand routines can expand or shrink an allocated memory 
block. They behave differently in cases in which there is not enough room to 
expand the block in its current location. In this case, realloc moves the block as 
needed, but _ expand does not. 


The calloc routine allocates memory for an array and initializes every byte in the 
allocated block to 0. 


The _halloc routine is similar to calloc, except that it can allocate memory for a 
huge array (one that exceeds 64K in size). This routine is useful when you need a 
very large data object, or if you need to return allocated memory to the operating 
system for subsequent calls to the _spawn family of functions. 


Near and Far Heaps 


As mentioned in the previous section, heap memory can reside inside or outside 
your program’s default data segment, depending on what memory model your 
program uses. When it lies inside the default data segment, the heap 1s called the 
“near heap,” since it can be accessed with near pointers. The “far heap” is memory 
that spans one or more segments outside the default data segment. The far heap 
can be accessed only with far pointers. 


In various memory models, malloc automatically allocates memory from the near 
heap or far heap, as appropriate. The run-time library also includes near and far 
versions of malloc, free, and other memory-management routines, which allow 
you to specify the near and far heaps explicitly. These have the same names as 
standard memory routines, but are preceded by _n (for near) or _f (for far). 
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For instance, the _nmalloc routine always allocates memory from the near heap 
and returns a near pointer, no matter which memory model your program uses. 
Use _nfree to release memory allocated with _ nmalloc. 


Similarly, _fmalloc always allocates memory from the far heap and returns a far 
pointer, regardless of memory model. Use the _ffree routine to release memory 
allocated with _ fmalloc. 


Based Heaps 


You can also allocate memory from a “based heap,” which is a single segment that 
lies outside the default data segment. Based-heap routines generally use the same 
names as standard memory routines, but begin with _b. For instance, _ bmalloc 
allocates a memory block from the based heap and _ bfree frees the block. 


Based heaps offer the following advantages: 


=" Localized data. Based heaps allow you to group related data in a single seg- 
ment. This can simplify the management of related data. 


= Faster pointer arithmetic. Although the based heap lies in the far data segment, 
pointers to its data items are the same size as near pointers. Thus, pointer arith- 
metic on items in a based heap is faster than pointer arithmetic on items in the 
far heap. 


The _ bheapseg routine allocates a based heap segment, from which you can then 
allocate blocks of memory. You can call _bheapseg more than once to allocate as 
many based-heap segments as needed (within the confines of available memory). 


The _ bfreeseg routine frees a based-heap segment. This routine frees every 
block in the based-heap segment, whether or not you previously freed the blocks 
individually. 


Note Near- , far- , and based-heap calls are not ANSI compatible and will make 
your program less portable. 


2.11 Process and Environment Control 


The process-control routines allow you to start, stop, and manage processes from 
within a program. Environment-control routines allow you to get and change infor- 
mation about the operating-system environment. 


50 Run-Time Library Reference 


A “process” is a program being executed by the operating system. It consists of 
the program’s code and data, plus information about the process, such as the num- 
ber of open files. Whenever you execute a program at the operating-system level, 
you start a process. All process-control functions except signal are declared in the 
include file PROCESS.H. The signal function is declared in SIGNAL.H. The 
abort, exit, and system functions are also declared in the STDLIB.H include file. 
The environment-control routines (getenv and _ putenv) are declared in 


STDLIB.H. 

Routine Use 

abort Aborts a process without flushing buffers or calling functions 
registered by atexit and _onexit 

assert Tests for logic error 

atexit Schedules routines for execution at program termination 

_cexit Performs the exit termination procedures (such as flushing buffers) 
and returns control to the calling program 

_c_exit Performs the _ exit termination procedures and returns control to the 
calling program 

_execl Executes child process with argument list 

_execle Executes child process with argument list and given environment 

_execlp Executes child process using PATH variable and argument list 

_execlpe Executes child process using PATH variable, given environment, and 
argument list 

_execv Executes child process with argument array 

_execve Executes child process with argument array and given environment 

_execvp Executes child process using PATH variable and argument array 

_execvpe Executes child process using PATH variable, given environment, and 
argument array 

exit Calls functions registered by atexit and _ onexit, then flushes all 
buffers and closes all open files before terminating the process 

_ exit Terminates process without processing atexit or _ onexit functions or 
flushing buffers 

_fatexit Schedules routines for execution at program termination (memory- 
model independent) 

_fonexit Schedules routines for execution at program termination (memory- 
model independent) 

getenv Gets the value of an environment variable 

_ getpid Gets process ID number 


longjmp 


Restores a saved stack environment 
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Routine Use 

_onexit Schedules routines for execution at program termination 

perror Prints error message 

_putenv Adds or changes the value of an environment variable 

raise Sends a signal to the calling process 

setjmp Saves a stack environment 

signal Handles an interrupt signal 

_spawnl Executes child process with argument list 

_spawnle Executes child process with argument list and given environment 

_Spawnlp Executes child process using PATH variable and argument list 

_spawnlpe Executes child process using PATH variable, given environment, and 
argument list 

_Spawnv Executes child process with argument array 

_spawnve Executes child process with argument array and given environment 

_Spawnvp Executes child process using PATH variable and argument array 

_Spawnvpe Executes child process using PATH variable, given environment, and 


argument array 
system Executes an operating-system command 


The atexit and _ onexit routines create a list of functions to be executed when the 
calling program terminates. The only difference between the two is that atexit is 
part of the ANSI standard. The _ onexit function is offered for compatibility with 
previous versions of Microsoft C. 


The _ exit routine terminates a process immediately, whereas exit terminates the 
process only after flushing buffers and calling any functions previously registered 
by atexit and _ onexit. The _ cexit and _c_ exit routines are identical to exit and 
_ exit, respectively, except that they return control to the calling program without 
terminating the process. 


The setjmp and longjmp routines save and restore a stack environment. These 
allow you to execute a nonlocal goto. 


The _ exec and _ spawn routines start a new process called the “child” process. 
The difference between the _ exec and _ spawn routines is that the _spawn 
routines are capable of returning control from the child process to its caller (the 
“parent” process). Both the parent process and the child process are present in 
memory (unless _P_OVERLAY is specified). In the _ exec routines, the child 
process overlays the parent process, so returning control to the parent process is 
impossible (unless an error occurs when attempting to start execution of the child 
process). 
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There are eight forms each of the _ exec and _spawn routines (see Table 2.1). The 
differences among the forms involve the method of locating the file to be executed 
as the child process, the method for passing arguments to the child process, and 
the method of setting the environment. 


Passing an argument list means that the arguments to the child process are listed 
separately in the _exec or _spawn call. Passing an argument array means that the 
arguments are stored in an array, and a pointer to the array is passed to the child 
process. The argument-list method is typically used when the number of argu- 
ments is constant or is known at compile time. The argument-array method is use- 
ful when the number of arguments must be determined at run time. 


Table 2.1 Forms of the _spawn and _ exec Routines 


Argument-Passing 


Routines Locating the File Convention Environment Settings 

_execl, _ spawnl Do notuse PATH ~—= Argument list Inherited from parent 

_execle, Do not use PATH ~— Argument list Pointer to environment 

_Spawnle table for child process 
passed as last argument 

_execip, Use PATH Argument list Inherited from parent 

_Spawnlp 

_execlpe, Use PATH Argument list Pointer to environment 

_Spawnlpe table for child process 
passed as last 
argument 

_ exec, Do notuse PATH Argument array Inherited from parent 

_spawnv 

_execve, Do not use PATH = Argument array Pointer to environment 

_Spawnve table for child process 
passed as last 
argument 

_execvp, Use PATH Argument array Inherited from parent 

_Spawnvp 

_execvpe, Use PATH Argument array Pointer to environment 

_Spawnvpe table for child process 
passed as last 
argument 


The assert macro is typically used to test for logic errors. It prints a message when 
a given “assertion” fails to hold true. Defining the identifier NDEBUG to any 
value causes occurrences of assert to be removed from the source file, thus allow- 
ing you to turn off assertion checking without modifying the source file. 
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2.12 QuickWin 


The QuickWin functions make it possible to compile non-Windows DOS pro- 
grams as simple text-only Windows applications. DOS programs compiled with 
the /Mg compiler option have a limited Windows user interface, including a stand- 
ard menu bar, standard online help (for the QuickWin features), and a client (or ap- 
plication) window with a child (document) window for the input/output streams 
stdin, stdout, and stderr. You can also add other child windows of your own. 
QuickWin applications support the Windows Clipboard, and you can use standard 
C and C++ functions to write to and read from a QuickWin application’s win- 
dows, which behave as streams. 


Unless you use the functions covered in this section, you do not need to alter your 
program’s source code. However, by using these functions in your source, you can 
take advantage of enhanced capabilities in your Quick Win programs. 


Note that there are some restrictions on the kinds of DOS programs that can be 
compiled with Quick Win. Programs that use graphics or that spawn processes can- 
not take advantage of QuickWin. For full details about QuickWin, see Chapter 8 
of Programming Techniques (in the Microsoft C/C++ version 7.0 documentation 
set). 


QuickWin programs cannot be run in real mode. 


QuickWin uses Windows libraries and the QWIN.LIB library. QuickWin con- 
stants, structures, and functions are declared in the Windows version of IO.H and 
STDIO.H. The /Mq compiler option defines the WINDOWS constant, declared 
in the Windows version of STDIO.H. 


Routine Use 

_fwopen Opens a new window stream 

_wabout Sets the string that appears in the About dialog box 
_wclose Closes a window’s file handle 

_weetexit Gets a Quick Win program’s current exit behavior setting 
_wegetfocus Returas a file handle to the window with the input focus 
_weetscreenbuf Gets a window’s current screen-buffer size 

_weetsize Gets a window’s current size and position on the screen 
_ wmenuclick Chooses a menu command 

_wopen Opens a window, returning a file handle to it 

_ wsetexit Sets the way a Quick Win program behaves when exit is called 
_wsetfocus Makes a window the active window (sets its focus) 
_wsetscreenbuf Sets a window’s screen-buffer size 

_ wsetsize Sets a window’s size and position on the screen 


_wyield Yields processor time to Windows for queue servicing 
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2.13 Searching and Sorting 


Search and sort routines provide binary-search, linear-search, and quick-sort capa- 
bilities. They are all declared in SEARCH.H. 


Routine Use 


bsearch 


Performs binary search 


_Ifind Performs linear search for given value 

_Isearch Performs linear search for given value, which is added to array if not 
found 

qsort Performs quick sort 


2.14 String Manipulation 


The string functions are declared in the include file STRING.H. They allow you to 
compare strings, copy them, search for strings and characters, and perform various 


other operations. 


Routines beginning with _f are model-independent versions of the corresponding 
routines and are useful in mixed-model programs. These routines can be called 
from any point in the program, regardless of which model is being used. 


Routine 


streat, _ fstrcat 
strchr, _ fstrchr 
strcmp, _ fstremp 
strepy, _ fstrepy 
strespn, _fstrcspn 


_strdup, _fstrdup, 
_nstrdup 


strerror 

_Strerror 

_stricmp, _ fstricmp 
strlen, _ fstrlen 
_striwr, _fstrlwr 
strncat, _ fstrncat 
strncmp, _fstrncmp 
strncpy, _fstrncpy 
_Strnicmp, _ fstrnicmp 


Use 


Append one string to another 

Find first occurrence of a given character in a string 
Compare two strings 

Copy one string to another 


Find first occurrence of a character from a given 
character set in a string 


Duplicate a string 


Maps an error number to a message string 
Maps a user-defined error message to a string 
Compare two strings without regard to case 
Find length of string 

Convert string to lowercase 

Append characters of a string 

Compare characters of two strings 

Copy characters of one string to another 


Compare characters of two strings without regard 
to case 


Routine 


_strnset, _ fstrnset 
strpbrk, _ fstrpbrk 


strrchr, _fstrrchr 
_strrev, _fstrrev 
_Strset, _ fstrset 
strspn, _ fstrspn 
strstr, _ fstrstr 
strtok, _ fstrtok 
_Strupr, _fstrupr 
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Use 


Set characters of a string to a given character 


Find first occurrence of a character from one string in 
another 


Find last occurrence of a given character in string 
Reverse a string 

Set all characters of a string to a given character 

Find first substring from a given character set in a string 
Find first occurrence of a given string 1n another string 
Find next token in a string 


Convert a string to uppercase 


All string functions work on null-terminated character strings. When working with 
character arrays that do not end with a null character, you can use the buffer- 
manipulation routines, described in “Buffer Manipulation” on page 18. 


2.15 System Calls 


The following routines give access to IBM-PC BIOS interrupts and DOS system 
calls. These routines are for DOS application programs only. 


BIOS Interface 


The functions in this category provide direct access to the BIOS interrupt services. 
They are all declared in BIOS.H. 


Routine 


_bios_ disk 


_bios_ equiplist 
_bios_keybrd 
_bios_memsize 
_bios_ printer 
_bios_serialcom 
_bios_ timeofday 


Use 

Issues service requests for both hard and floppy disks, using 
INT 0x13 

Performs an equipment check, using INT 0x11 

Provides access to keyboard services, using INT 0x16 
Obtains information about available memory, using INT 0x12 
Performs printer output services, using INT 0x17 

Performs serial communications tasks, using INT 0x14 
Provides access to system clock, using INT OxlA 


Note BIOS routines are hardware dependent. Some of them may not work as ex- 
pected on machines whose hardware differs from the IBM PC. 
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DOS Interface 


These routines are implemented as functions and declared in DOS.H. 


Routine 


_bdos 

_chain_ intr 

_ disable 
_dos_allocmem 
_dos_close 
_dos_ commit 
_dos_creat 


_dos_creatnew 
_ dos_findfirst 
_ dos_findnext 


_dos_freemem 
_dos_ getdate 

_ dos_getdiskfree 
_ dos_getdrive 

_ dos_getfileattr 


_dos_getftime 


_dos_gettime 
_dos_getvect 


_dos_keep 


_dos_open 
_dos_read 
_ dos_setblock 


_dos_setdate 
_dos_setdrive 
_dos_setfileattr 
_dos_setftime 


_ dos_settime 


Use 


Invokes DOS system call; uses only DX and AL registers 
Chains one interrupt handler to another 

Disables interrupts 

Allocates a block of memory, using DOS system call 0x48 
Closes a file, using DOS system call Ox3E 

Flushes a file to disk, using DOS system call 0x68 


Creates a new file and erases any existing file having the same 
name, using DOS system call Ox3C 


Creates a new file and returns an error if a file having the same 
name exists, using DOS system call 0x5B 


Finds first occurrence of a given file, using DOS system call 
Ox4E | | 


Finds subsequent occurrences of a given file, using DOS system 
call Ox4F 


Frees a block of memory, using DOS system call 0x49 

Gets the system date, using DOS system call 0x2A 

Gets information on a disk volume, using DOS system call 0x36 
Gets the current default drive, using DOS system call 0x19 


Gets current attributes of a file or directory, using DOS system 
call 0x43 


Gets the date and time a file was last written, using DOS system 
call 0x57 


Gets the current system time, using DOS system call 0x2C 


Gets the current value of a specified interrupt vector, using DOS 
system call 0x35 


Installs terminate-and-stay-resident (TSR) programs using DOS 
system call 0x31 


Opens an existing file, using DOS system call 0x3D 
Reads a file, using DOS system call 0x3F 


Changes the size of a previously allocated block, using DOS 
system call Ox4A 


Sets the current system date, using DOS system call 0x2B 
Sets the default disk drive, using DOS system call 0xOE 
Sets the current attributes of a file, using DOS system call 0x43 


Sets the date and time that the specified file was last written, 
using DOS system call 0x57 


Sets the system time, using DOS system call 0x2D 
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Routine Use 

_dos_setvect Sets a new value for the specified interrupt vector, using DOS 
system call 0x25 

_dos_ write Sends output to a file, using DOS system call 0x40 

_dosexterr Obtains in-depth error information from DOS system call 0x59 

_ enable Enables interrupts 

_FP_OFF Returns offset portion of a far pointer 

_FP_SEG Returns segment portion of a far pointer 

_harderr Establishes a hardware error handler 

_hardresume Returns to DOS after a hardware error 

_hardretn Returns to the application after a hardware error 

_int86 Invokes DOS interrupts 

_int86x Invokes DOS interrupts with segment register values 

_intdos Invokes DOS system call using registers other than DX and AL 

_intdosx Invokes DOS system call using registers other than DX and AL 


with segment register values 
_Segread Returns current values of segment registers 


The _ dosexterr function obtains and stores the error information returned by 
DOS system call 0x59 (extended error handling). This function is provided for use 
with DOS versions 3.0 and later. 


The _ bdos routine is useful for invoking DOS calls that use either or both of the 
DX (DH/DL) and AL registers for arguments. However, _ bdos should not be 
used to invoke system calls that return an error code in AX if the carry flag is set; 
since your program cannot detect whether the carry flag is set, it cannot determine 
whether the value in AX is a legitimate value or an error value. In this case, the 
_intdos routine should be used instead, since it allows the program to detect 
whether the carry flag is set. The _intdos routine can also be used to invoke DOS 
calls that use registers other than DX and AL. 


The _intdosx routine is similar to the _intdos routine, but is used when ES is re- 
quired by the system call, when DS must contain a value other than the default 
data segment (for instance, when a far pointer is used), or when making the system 
call in a large-model program. When calling _ intdosx, give an argument that 
specifies the segment values to be used in the call. 


The _int86 routine can be used to invoke any interrupt. The _ int86x routine is 
similar; however, like the _intdosx routine, it is designed to work with large- 
model programs and far items, as described in the preceding paragraph. 


The _FP_OFF and _FP_SEG routines allow easy access to the segment and off- 
set portions of a far pointer value. _FP_OFF and _FP_SEG are implemented as 
macros and defined in DOS.H. 
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2.16 Time 


The _segread routine returns the current values of the segment registers. This 
routine is typically used with the _intdosx and _ int86x routines to obtain the 
correct segment values. 


The _ chain_ intr routine is useful for chaining interrupt handlers together. The 
_ enable routine enables interrupts, while the _ disable routine disables interrupts. 


The routines prefixed with _dos_ are all direct system interfaces that use the 
system calls noted above. More detailed information on these system calls can be 
found in the MS-DOS Encyclopedia (Duncan, ed.; Redmond, WA: Microsoft 
Press, 1988) or the Programmer’s PC Sourcebook 2nd ed. (Hogan; Redmond, 
WA: Microsoft Press, 1991). 


Note The DOS interface I/O routines are generally incompatible with console, 
low-level, and stream I/O routines. Do not mix different types of I/O routines in 
the same source file. 


The time functions allow you to obtain the current time, then convert and store it 
according to your particular needs. The current time is always taken from the 


system time. 


Routine 


asctime 
clock 
ctime 
difftime 
_ftime 
gmtime 
localtime 
mktime 
_Sstrdate 
strftime 
_Strtime 
time 
_tzset 
_utime 


Use 


Converts time from type struct tm to a character string 

Returns the elapsed CPU time for a process 

Converts time from type time_t to a character string 

Computes the difference between two times 

Puts current system time in variable of type struct _timeb 
Converts time from type time_t to struct tm 

Converts time from type time_t to struct tm with local correction 
Converts time to a calendar value 

Returns the current system date as a string 

Formats a date and time string 

Returns the current system time as a string 

Gets current system time as type time_t 

Sets external time variables from the environment time variable 
Sets file-modification time 


The time and _ftime functions return the current time as the number of seconds 
elapsed since midnight, on December 31, 1899, Universal Coordinated Time. This 
value can be converted, adjusted, and stored in a variety of ways by using the 
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asctime, ctime, gmtime, localtime, and mktime functions. The _ utime function 
sets the modification time for a specified file, using either the current time or a 
time value stored in a structure. 


Note In versions of Microsoft C/C++ prior to 7.0, the time and _ ftime functions 
return the current time as the number of seconds elapsed since midnight, on 
January 1, 1970. 


The clock function returns the elapsed CPU time for the calling process. 


The _ftime function requires two files: SYS\TYPES.H and SYS\TIMEB.H. It is 
declared in SYS\TIMEB.H. The _ utime function also requires two include files: 
SYS\TYPES.H and SYS\UTIME.H. It is declared in SYS\UTIME.H. The re- 
mainder of the time functions are declared in the include file TIME.H. 


When you want to use _ ftime or localtime to make adjustments for local time, 
you must define an environment variable named TZ. For more information on TZ 
and the global variables _ daylight, _ timezone, and _tzname, refer to “_daylight, 
_timezone, and _tzname” on page 62. TZ is also described on the _ tzset reference 
page in Part 2 of this book. 


The _ strdate and _strtime routines return strings containing the current date and 
time, respectively, in the DOS and Windows date and time format rather than in 
the UNIX-style formats. 


The strftime function is useful for creating international versions of a program. 
See “Internationalization’ on page 44. 


2.17 Variable-Length Argument Lists 


The va_arg, va_end, and va_start routines are macros that provide a portable 
way to access the arguments to a function when the function takes a variable num- 
ber of arguments. Two versions of the macros are available: the macros defined in 
the VARARG.H include file, which are compatible with the UNIX System V defi- 
nition, and the macros defined in STDARG.H, which conform to the ANSI C 


standard. 

Routine Use 

va_arg Retrieves argument from list 

va_end Resets pointer 

va_ start Sets pointer to beginning of argument list 


For more information on the differences between the two versions and for an ex- 
planation of how to use the macros, see their descriptions in Part 2 of this book. 
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2.18 Virtual Memory Allocation 


The virtual memory functions allow you to allocate, free, reallocate, lock, and un- 
lock blocks of memory. The virtual memory functions are declared in the include 
file VMEMORY.H. 


Routine Use 

__Vfree Frees an allocated block of virtual memory 

_ vheapinit Initializes the virtual memory manager 

_Vvheapterm Terminates the virtual memory manager 

_ Vload Loads an allocated block of virtual memory 

_Vlock Locks an allocated block of virtual memory 

_ Vvilockent Returns the number of locks held on a block of virtual memory 
_vmalloc Allocates a block of virtual memory 

_vmsize Returns the size of an allocated block of virtual memory 
_ vrealloc Reallocates a block of virtual memory to a new size 

_ vunlock Unlocks a locked block of virtual memory 


The _ vheapinit function specifies how much DOS memory the virtual memory 
manager can use and whether it should use expanded memory, extended memory, 
or disk storage. You must call this function before calling any of the other virtual 
memory functions. 


The _ vmalloc function returns a handle of type _vmhnd_t, which is used to refer 
to a block of virtual memory. 


The _ vfree, _ vrealloc, _ vload, _ viock, _ vunlock, _ vlockent, and _ vmsize func- 
tions work on blocks of virtual memory specified by handles of type _ vmdhnd_ t. 


The _ vheapterm function frees all the resources used by the virtual memory 
manager. You must call this function after you have finished using virtual 
memory. 


Global Variables 
and Standard Types 


The Microsoft run-time library contains definitions for a number of variables and 
standard types used by library routines. You can access these variables and types 
by including in your program the files in which they are declared, or by giving 
appropriate declarations in your program, as shown in the following sections. 


3.1 _amblksiz 


The _amblksiz variable controls memory heap granularity. 
It is declared in the MALLOC.H include file as follows: 
extern unsigned int _amblksiz; 


The value of _amblksize is used to control how memory is obtained from the 
operating system for the heap. The initial requested size for a segment of memory 
for the heap manager is based on the amount of current allocation request plus 
overhead for the heap manager’s bookkeeping chores—that 1s, just enough to 
satisfy the allocation request at hand (for example, a malloc or calloc). However, 
when the heap manager grows a segment, it does so in multiples of _ amblksize. 
The value of _ amblksize represents a trade-off between the number of times the 
operating system must be called to grow a segment to its maximum size (no more 
than 640K for DOS) and the amount of memory potentially wasted (available but 
not used) at the end of the heap. 


The default value of _amblksize is 8K. The value can be changed by direct assign- 
ment in your program. For example: 


_amblksize = 2048; 


The actual value used internally by the heap manager will be the given value, 
rounded up to the nearest whole power of 2 (so an __amblksize value of 4K—1 is 
the same as a value of 4K). 
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Note that adjusting the value of _amblksize affects allocation in the near, far, and 
based heaps. The value of _ amblksize has no effect on huge memory blocks 
(those allocated with _halloc and similar functions). 


3.2 _ daylight, timezone, tzname 


The _ daylight, _ timezone, and _ tzname variables are global time-zone variables 
used in time functions. 


They are declared in the TIME.H include file as follows: 
extern int _ daylight; 

extern long _ timezone; 

extern char *_tzname[2]; 


Some time and date routines use the _ daylight, _ timezone, and _ tzname varia- 
bles to make local-time adjustments. Whenever a program calls the _ ftime, 
localtime, or _tzset function, the value of _ daylight, _ timezone, and _ tzname is 
determined from the value of the TZ environment variable. If you do not explicitly 
set the value of TZ, the default value of “PST8PDT” is used. The following list 
shows each variable and its value: 


Variable Value 

_ daylight Nonzero if a daylight-saving-time zone (DST) is specified in TZ; 
otherwise, 0. Default value is 1. 

_ timezone Difference in seconds between Universal Coordinated Time and the 
local time. Default value is 28,800. 

_tzname[0] Three-letter time-zone name derived from the TZ environment 


variable. Default value is “PST” (Pacific standard time). 

_tzname[1] Three-letter daylight-saving-time-zone name derived from the TZ 
environment variable. Default value is “PDT” (Pacific daylight time). 
If the DST zone is omitted from TZ, _tzname[1] is an empty string. 
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3.3 _ doserrno, errno, sys_errlist, sys_nerr 


The _ doserrno, errno, sys_errlist, and sys_nerr variables contain error codes 
and are used by the perror and strerror routines to print error information. 


These variables are declared in the STDLIB.H include file. Manifest constants for 
the errno variables are declared in the ERRNO.H include file. The declarations 
are as follows: 


extern int _ doserrno; 
extern int errno; 

extern char *sys_errlist[ |; 
extern int sys_nerr; 


The errno variable is set to an integer value to reflect the type of error that has oc- 
curred in a system-level call. Each errno value is associated with an error mes- 
sage, which can be printed with the perror routine or stored in a string with the 
strerror routine. 


Note that only some routines set the errno variable. If a routine sets errno, the 
description of the routine in the reference section says so explicitly. 


The value of errno reflects the error value for the last call that set errno. How- 
ever, this value is not necessarily reset by later successful calls. To avoid confu- 
sion, test for errors immediately after a call. 


The include file ERRNO.H contains the definitions of the errno values. However, 
not all of the definitions given in ERRNO.H are used in DOS. Some of the values 
in ERRNO.H are present to maintain compatibility with the UNIX (and XENIX) 
operating system. 


The errno values in DOS are a subset of the values for errno in XENIX systems. 
Thus, the errno value is not necessarily the same as the actual error code returned 
by a DOS system call. To access the actual DOS error code, use the _ doserrno 
variable, which contains this value. 


In general, you should use _ doserrno only for error detection in operations involv- 
ing input and output, since the errno values for input and output errors have DOS 
error-code equivalents. In other cases, the value of _doserrno is undefined. 
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The sys_errlist variable is an array; the perror and strerror routines use it to 
process error information. The sys_nerr variable tells how many elements the 
sys_errlist array contains. 


Table 3.1 gives the errno values for DOS, the system error message for each 


value, and the value of each constant. Note that only the ERANGE and EDOM 
constants are specified in the ANSI standard. 


Table 3.1 errno Values and Their Meanings 


Constant Meaning Value 
E2BIG Argument list too long 7, 
EACCES Permission denied 13 
EBADF Bad file number 9 
EDEADLOCK Resource deadlock would occur 36 
EDOM Math argument 33 
EEXIST File exists 17 
EINVAL Invalid argument De 
EMFILE Too many open files 24 
ENOENT No such file or directory 

ENOEXEC Exec format error 8 
ENOMEM Not enough memory | 12 
ENOSPC No space left on device 28 
ERANGE Result too large 34 
EXDEV Cross-device link 18 


3.4 fmode 


The _fmode variable controls the default file-translation mode. 
It is declared in the STDLIB.H include file as follows: 
extern int _fmode; 


By default, the value of _fmode is _O_ TEXT, causing files to be translated in 
text mode (unless specifically opened or set to binary mode). When _fmode is set 
to _O_BINARY, the default mode is binary. You can set _fmode to the flag 
_O_ BINARY by linking with BINMODE.OBJ or by assigning _fmode the 
_QO_ BINARY value. 
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3.5 Locale Macros 


The two ANSI macros, MB_ LEN_ MAX and MB_CUR_ MAX, are useful when 
writing portable programs for international markets. The following list describes 
them and gives the include file where each is defined. 


Macro Description 


MB_CUR_MAX The MB_CUR_MAX macro, defined in STDLIB.H, expands to 
the maximum number of bytes in a multibyte character of the 
current locale. 

MB_LEN_MAX The MB_LEN_MAX macro, defined in LIMITS.H, gives the 
maximum number of bytes in a multibyte character. 


3.6 _osmajor, oSsminor, osmode, osversion, cpumode 


The _osmajor, _ osminor, _ osmode, _ osversion, and _ cpumode variables 
specify the version number of the operating system or the current mode of 
operation. 


They are declared in the STDLIB.H include file as follows: 
extern unsigned char _ osmajor; 

extern unsigned char _ osminor; 

extern unsigned char _ osmode; 

extern unsigned char _ osversion; 

extern unsigned char _cpumode; 


The _osmajor, _ osminor, and _ osversion variables specify the version number 
of DOS or Windows in use. The _ osmajor variable holds the “major” version 
number, and the _osminor variable stores the “minor” version number. Thus, 
under DOS version 5.0, _osmajor is 5 and _osminor is 0. The _ osversion varia- 
ble holds both values: its low byte contains the major version number and its high 
byte contains the minor version number. 


These variables are useful for creating programs that run in different versions of 
DOS and Windows. For example, you can test the _osmajor variable before 
making a call to _sopen; if the major version number is earlier (less) than 3, 
_open should be used instead of _ sopen. 
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3./ environ 


3.8 _ psp 


The _osmode variable indicates the currently running operating system— 
_DOS_MODE, which is defined as 0, and. WIN_ MODE, which is defined as 2. 


The _cpumode variable indicates the mode of the currently running operating 
system—_REAL_MODE, which is defined as 0, and _PROT_MODE, which is 
defined as 2. 


The environ variable is a pointer to the strings in the process environment. 
It is declared in the STDLIB.H include file as follows: 
extern char “environ[ |; 


The environ variable provides access to memory areas containing process-specific 
information. 


The environ variable is an array of pointers to the strings that constitute the 
process environment. The environment consists of one or more entries of the form 


NAME=string 


where NAME is the name of an environment variable and string is the value of 
that variable. The string can be empty. The initial environment settings are taken 
from the operating-system environment at the time of program execution. 


The getenv and _ putenv routines use the environ variable to access and modify 
the environment table. When _ putenv is called to add or delete environment set- 
tings, the environment table changes size; its location in memory may also change, 
depending on the program’s memory requirements. The environ variable is ad- 
justed in these cases and always points to the correct table location. 


The _ psp variable contains the segment address of the program segment prefix 
(PSP) for the process. It is declared in the STDLIB.H include file as follows: 


extern unsigned int _ psp; 


The PSP contains execution information about the process, such as a copy of the 
command line that invoked the process and the return address on process termina- 
tion or interrupt. The _ psp variable can be used to form a long pointer to the PSP, 
where _ psp is the segment value and 0 is the offset value. 
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Note that the _ psp variable is supported only in DOS. 


3.9 _pgmotr 


The _ pgmptr variable is automatically initialized at startup to point to the full 
path of the executing program. It is defined as a global variable in the run-time 
library and declared in CRTODAT.ASM, which is part of the startup code. This 
code is linked to any module that contains a main function. Declaring _ pgmptr 
in your own code is all that is required to make the full path available to your 
program: 


extern char __ far *_pgmptr; 

The following program demonstrates the use of _ pgmptr: 

#Finclude <stdio.h> 

extern char __far *_pgmptr; 

void main( void ) 

printf("The full path of the executing program is : %Fs\n", 


_pgmptr); 
.) 


In DOS versions 3.0 and later, argv[O] also contains a pointer to the full path of 
the executing program. 


3.10 Standard Types 


A number of library routines use values whose types are defined in include files. 
The following list describes these types and gives the include file where they are 
defined. | 


Standard Type Description 


clock_t The clock_t type, defined in TIME.H, stores time values. It is 
used by the clock function. 

_complex The _ complex structure, defined in MATH.H, stores the real and 
imaginary parts of complex numbers. It is used by the _cabs 
function. 

_diskfree_t The _ diskfree_t structure, defined in DOS.H, stores disk 
information used by the _dos_ getdiskfree routine. 

_ diskinfo_t The _ diskinfo_t structure, defined in BIOS.H, records 


information about disk drives returned by the _ bios_ disk routine. 
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Standard Type 
div_t, Idiv_t 


_ dosdate_t 


_ dostime_t 


_DOSERROR 


_exception 


FILE 


_find_t 


fpos_t 


jmp_buf 


lconv 


_ onexit_t 


ptrdiff_t 


_REGS 


Sig_ atomic_t 


size_t 


Description 


The div_t and Idiv_t structures, defined in STDLIB.H, store the 
values returned by the div and Idiv functions, respectively. 


The _dosdate_t structure, defined in DOS.H, records the current 
system date used in the _ dos_ getdate and _ dos_setdate 
routines. | 


The _dostime_t structure, defined in DOS.H, records the current 
system time used in the _dos_ gettime and _dos_settime 
routines. 


The _DOSERROR structure, defined in DOS.H, stores values 
returned by DOS system call 59H (available with DOS versions 
3.0 and later). | 


The _ exception structure, defined in MATH.H, stores error 
information for math routines. It is used by the _matherr routine. 


The FILE structure, defined in STDIO.H, is the structure used in 
all stream input and output operations. The fields of the FILE 
structure store information about the current state of the stream. 


The _find_t structure, defined in DOS.H, stores file-attribute 
information returned by the _ dos_findfirst and _ dos_findnext 
routines. 


The fgetpos and fsetpos functions use the fpos_t object type, 
defined in STDIO.H, to record all the information necessary to 
uniquely specify every position within the file. 


The jmp_ buf type, defined in SETJMP.H, is an array type rather 
than a structure type. A buffer of this type is used by the setjmp 
and longjmp routines to save and restore the program 
environment. 

The Iconv type, defined in LOCALE.H, is a structure containing 
formatting rules for numeric values in different countries. 

The _onexit routine is declared as an _onexit_t pointer type, 
which is defined in STDLIB.H. 

The ptrdiff_t type is used for the signed integral result of the 
subtraction of two pointers. 

The _ REGS union, defined in DOS.H, stores byte and word 
register values to be passed to and returned from calls to the DOS 
interface functions. 

The sig_ atomic_t type, defined in SIGNAL.H, is the integral 
type of an object that can be modified as an atomic entity, even in 
the presence of asynchronous interrupts. It is used in conjunction 
with the signal routine. 

The size_t type, defined in STDDEEF.H and several other include 
files, is the unsigned integral result of the sizeof operator. 


Standard Type 
_SREGS 


_ Stat 
time_t 
_timeb 


tm 


_utimbuf 


va_list 


_vmhnd_t 


wchar_t 


_wopeninfo 


_ wsizeinfo 


Global Variables and Standard Types 


Description 


The _SREGS structure, defined in DOS.H, stores the values of 
the ES, CS, SS, and DS registers. This structure is used by the 
DOS interface functions that require segment register values 

(_ int86x, _ intdosx, and _ segread). 

The _ stat structure, defined in SYS\STAT.H, contains file-status 
information returned by the _stat and _fstat routines. 

The time_t type, defined in TIME.H, represents time values in 
the mktime and time routines. 

The _timeb structure, defined in SYS\TIMEB.H, is used by the 
_ftime routine to store the current system time. 

The tm structure, defined in TIME.H, is used by the asctime, 
emtime, and localtime functions to store and retrieve time 
information. 

The _utimbuf structure, defined in SYS\UTIME.H, stores file 
access and modification times used by the _ utime function to 
change file-modification dates. 


The va_list array type, defined in STDARG.H, is used to hold 


information needed by the va_arg macro and the va_end routine. 


The called function declares a variable of type va_list, which can 
be passed as an argument to another function. 


The _vmhnd_t type, defined in VMEMORY.H, represents the 
handles to blocks of virtual memory. Handles of this type are 
returned by _ vmalloc and used by the virtual memory routines. 


The wchar_t type, defined in STDDEF.H and STDLIB.H, is the 
internal type of a wide character. It is required by the ANSI 
standard for the C language and is useful when writing portable 
programs for international markets. 


The _ wopeninfo type is a structure containing information 
needed to open a new QuickWin window. It is defined in IO.H. 


The _ wsizeinfo type is a structure containing information needed 
to initialize the size of a new QuickWin window, to examine the 
size of an existing Quick Win window, or to resize an existing 
Quick Win window. It is defined in IO.H. 
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About the Run-Time Reference 


The following pages describe, in alphabetical order, the more than 550 functions 
and macros in the Microsoft run-time library. In some cases, related routines are 
clustered in the same description. For example, the based, near, and far versions of 
_heapwalk are in the same discussion, as are the regular and long double versions 
of the math functions, such as acos and atan. Differences are noted where appro- 
priate. Refer to Chapter 2, “Run-Time Routines by Category,” or to the index to lo- 
cate any function that does not appear in the expected position within the 
alphabetical reference. 


The discussion of each function (or group of functions) is divided into the follow- 
ing sections: 


= Description. Summarizes the routine’s effect, names the include file(s) contain- 
ing its declaration, illustrates the syntax, and briefly describes the arguments. 

= Remarks. Gives a more detailed description of the routine and how it is used. 

= Return Value. Describes the value returned by the routine. 


= Compatibility. Tells whether the routine is compatible with ANSI C, UNIX, 
DOS, QuickWin, Windows, and the DOS Extender (DOS32X). 


= See Also. Names related routines. 
= Example. Gives a complete program showing the use of the routine. 


= Output. Shows the output from the example program. 


76 abort 


Description 


Remarks 


Return Value 


Compatibility 


See Also 


abort 


Aborts the current process and returns an error code. 


#include <process.h> Required only for function declarations; use either 
#include <stdlib.h> PROCESS.H or STDLIB.H 


void abort( void ); 


The abort function prints the message 


abnormal program termination 


to stderr, then calls raise(SIGABRT). The action taken in response to the 
SIGABRT signal depends on what action has been defined for that signal in a 
prior call to the signal function. The default SIGABRT action is for the calling 
process to terminate with exit code 3, returning control to the parent process or 
operating system. 


In Windows, the abort function does not call raise(SIGABRT). Instead, it termi- 
nates the process with an “Abnormal Program Termination” pop-up message. In 
Windows multithread libraries, the abort function does not call raise(SIGABRT). 
Instead, it terminates the process with exit code 3. 


The abort function does not flush stream buffers or do atexit /_onexit processing. 


The abort function does not return control to the caller. Rather, it terminates the 
process and, by default, returns an exit code of 3 to the parent process. | 


Standards: ANSI, UNIX 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 


_exec functions, exit, _ exit, raise, signal, _ spawn functions 


abort 


Example /* ABORT.C: This tries to open a file and aborts if the attempt fails. */ 


dFinclude <stdio.h> 
dHinclude <stdlib.h> 


void main( void ) 


{ 
FILE *stream; 
if( (stream = fopen( "NOSUCHF.ILE", "r" )) == NULL ) 
ti 
perror( “Couldn't open file" ); 
abort(); 
} 
else 
fclose( stream ); 
I 
Output Couldn't open file: No such file or directory 


abnormal program termination 
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78 abs 


abs 


Description Calculates the absolute value. 
#include <stdlib.h> Required only for function declarations; use either 
#include <math.h> STDLIB.H or MATH.H 


int abs( int 7 ); 


n Integer value 
Remarks The abs function returns the absolute value of its integer argument n. 
Return Value The abs function returns the absolute value of its argument. There is no error 
return. 
Compatibility Standards: ANSI, UNIX 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 
See Also _cabs, fabs, labs 


Example /* ABS.C: This program computes and displays the absolute values of 
* Several numbers. 
* / 


deinclude <stdio.h> 
d4Finclude <math.h> 
dAinclude <stdlib.h> 


void main( void ) 

{ 
int ix SA. oye 
long ie. S41 56714. Vy 
double dx = -3.141593, dy; 


iy = abs( ix ); 
printf( "The absolute value of 4d is 4d\n", ix, iy); 


ly = labs( 1x ); 
printf( "The absolute value of %1ld is 41d\n", 1x, ly); 


Output 


dy = fabs( dx ); 
printf( "The absolute value of %4f is %f\n", dx, dy ); 


The absolute value of -4 is 4 
The absolute value of -41567 is 41567 
The absolute value of -3.141593 is 3.141593 


abs 
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80 _ access 


Description 


Remarks 


Return Value 


_ aCCESS 


Determines file-access permission. 


#include <io.h> Required only for function declarations 


#include <errno.h> Required for definition of errno constants 
int _access( char *pathname, int mode ); 


pathname File or directory path name 


mode Permission setting 


With files, the _ access function determines whether the specified file exists and 
can be accessed in mode. The possible mode values and their meanings in the 
_access call are as follows: 


Value Meaning 

00 Check for existence only 

02 Check for write permission 

04 Check for read permission 

06 Check for read and write permission 


With directories, _ access determines only whether the specified directory exists; 
in DOS, all directories have read and write access. | 


The _ access function returns the value 0 if the file has the given mode. A return 
value of —1 indicates that the named file does not exist or is not accessible in the 
given mode, and errno is set to one of the following values: 


Value Meaning 


EACCES Access denied: the file’s permission setting does not allow the 
specified access. 


ENOENT File or path name not found. 


_ access 81 


Compatibility Standards: UNIX 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 


Use _ access for compatibility with ANSI naming conventions of non-ANSI func- 
tions. Use access and link with OLDNAMES.LIB for UNIX compatibility. 


See Also _chmod, _ fstat, _ open, _ stat 


Example /* ACCESS.C: This example uses _access to check the file named "data" 
* to see if it exists and if writing is allowed. 
* / 
#include <io.h> 
#include <stdio.h> 
#include <stdlib.h> 


void main( void ) 


{ 
/* Check for existence */ 
if( (_access( "access.c", @ )) != -1 ) 
{ 
printf( "File exists\n" ); 
/* Check for write permission */ 
if( (_access( "access.c", 2 )) != -l1 ) 
printf( "File has write permission\n" ); 
} 
i 
Output File exists 


File has write permission 


82 acos Functions 


acos Functions 


Description Calculate the arccosine. 


#include <math.h> 


#include <errno.h> Required for definition of errno constant 


double acos( double x ); 


long double _ acosl( long double x ); 


x Value whose arccosine 1s to be calculated 


Remarks The acos functions return the arccosine of x in the range 0 to 7 radians. The value 
of x must be between —1 and 1. The _acosl function is the 80-bit counterpart, 
which uses an 80-bit, 10-byte coprocessor form of arguments and return values. 
See the reference page on the long double functions for more details on this 
data type. 


Return Value The acos functions return the arccosine result. If x is less than —1 or greater than 1, 
the function sets errno to EDOM, prints a_ DOMAIN error message to stderr, 
and returns 0. Error handling can be modified with the _ matherr (or _matherrl) 


routine. 
Compatibility acos 
Standards: ANSI, UNIX 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 
_acosl 


Standards: None 


16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: None 
See Also asin functions, atan functions, cos functions, _matherr, sin functions, tan 


functions 


Example 


Output 


/* 


*k 


* 


* 


* / 


acos Functions 


ASINCOS.C: This program prompts for a value in the range -1 to l. 
Input values outside this range will produce _DOMAIN error messages. 
If a valid value is entered, the program prints the arcsine and the 
arccosine of that value. 


#Hinclude <math.h> 

#tinclude <stdio.h> 
#Hinclude <stdlib.h> 
fHinclude <errno.h> 


void main( void ) 


{ 


double x, y; 


printf( “Enter a real number between -1 and 1: ™ ); 
scanf( "Z1f", &x ); 

y = asin( x ); 

printf( "Arcsine of “4f = %f\n", x, y ); 

y = acos( x ); 

printf( "“Arccosine of “4f = %f\n", x, y ); 


Enter a real number between -1 and 1: .32696 
Arcsine of @.326960@ = 0.333085 
Arccosine of @.326960 = 1.237711 
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84 —_ alloca 


Description 


Remarks 


—_ alloca 


Allocates memory on the stack. 
#include <malloc.h> Required only for function declarations 
void *_alloca( size_t size ); 


size Bytes to be allocated from stack 


The _ alloca routine allocates size bytes from the program’s stack. The allocated 
space is automatically freed when the calling function is exited. 


Observe the following restrictions when using _ alloca: 


=# When you compile with optimization on (either by default or by using one of 
the /O options), the stack pointer may not be restored properly in functions that 
have no local variables and that also reference the _ alloca function. (This re- 
striction does not apply to DOS32X.) The following program demonstrates the 
problem: 


/* Compile with CL /AM /0x /Fc */ 
#tAinclude <malloc.h> 


void main( void ) 
{ 

func( 10 ); 
} 


void func( register int i ) 


_alloca( i ); 
} 


To ensure that the stack pointer is properly restored, make sure that any func- 
tion referencing — alloca declares at least one local variable. 


= The pointer value returned by _ alloca should never be passed as an argument 
to free. 


= The _alloca function should never be used in an expression that is an argument 
to a function. 


Return Value 
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The _ alloca routine returns a void pointer to the allocated space, which is 
guaranteed to be suitably aligned for storage of any type of object. To get a pointer 
to a type other than char, use a type cast on the return value. The return value is 
NULL if the space cannot be allocated. 


Compatibility Standards: UNIX 
16-Bit: DOS 
32-Bit: DOS32X 


See Also 


Example 


Output 


Use _alloca for compatibility with ANSI naming conventions of non-ANSI func- 
tions. Use alloca and link with OLDNAMES.LIB for UNIX compatibility. 


calloc functions, malloc functions, realloc functions 


/* ALLOCA.C: This program checks the stack space available before 
* and after using the _alloca function to allocate space on the stack. 
* / 


d#Ainclude <malloc.h> 
dAinclude <stdio.h> 


void main( void ) 


{ 
char *buffer; 
printf( “Bytes available on stack: %4u\n", _stackavail() ); 
/* Allocate memory for string. */ 
buffer = _alloca( 120 * sizeof( char ) ); 
printf( "The _alloca function just allocated" ); 
printf( " memory from the program stack.\n" ); 
printf( "Enter a string: " ); 
gets( buffer ); 
printf( "\"%s\" was stored in the program stack.\n", buffer ); 
printf( "Bytes available on stack: %4u\n", _stackavail() ); 
j 


Bytes available on stack: 1744 

The _alloca function just allocated memory from the program stack. 
Enter a string: Store this on the stack. 

"Store this on the stack." was stored in the program stack. 

Bytes available on stack: 1614 
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Description 


Remarks 


_are Functions 


Draw elliptical arcs. 
#include <graph.h> 
short __ far _are( short x/, short y/, short x2, short y2, short x3, short y3, 


short x4, short y4 ); 


short __ far _arc_ w( double x/, double y/, double x2, double y2, double x3, 
double y3, double x4, double y4 ); 


short __ far _arc_ wxy( struct _wxycoord __ far *pwxy1/, 
struct _wxycoord __ far *pwxy2, struct _wxycoord __far *pwxy3, 
struct _wxycoord __ far *pwxy4 ); 


xl, yl Upper-left corner of bounding rectangle 

x2, y2 Lower-right corner of bounding rectangle 

x3, y3 Second point of start vector (center of bounding 
rectangle 1s first point) 

x4, y4 Second point of end vector (center of bounding rec- 
tangle is first point) 

pwxyl Upper-left corner of bounding rectangle 

pwxy2 Lower-right corner of bounding rectangle 

pwxy3 Second point of start vector (center of bounding 


rectangle 1s first point) 


pwxy4 Second point of end vector (center of bounding rec- 
tangle is first point) 


The _ arc functions draw elliptical arcs. The center of the arc is the center of the 
bounding rectangle, which is defined by points (x/, y/) and (x2, y2) for _are and 
_arc_w and by points pwxyl and pwxy2 for _arc_wxy. The arc starts where it in- 
tersects an imaginary line extending from the center of the arc through (x3, y3) for 
_are and _arc_w and through pwxy3 for _ arc_wxy. It is drawn counterclock- 
wise about the center of the arc, ending where it intersects an imaginary line ex- 
tending from the center of the arc through (x4, y4) for __are and _arc_w and 
through pwxy4 for _arc_wxy. 


Return Value 
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The _ are routine uses the view coordinate system. The _arc_w and _arc_wxy 
functions use the real-valued window coordinate system. 


In each case, the arc is drawn using the current color. Since an arc does not define 
a closed area, it is not filled. 


These functions return a nonzero value if the arc is successfully drawn; otherwise, 


they return 0. 
Compatibility Standards: None 

16-Bit: DOS 

32-Bit: None 


See Also 


Example 


_ ellipse functions, _lineto functions, _ pie functions, _rectangle functions, 
_setcolor 


/* ARC.C: This program draws a simple arc. */ 


#Hinclude <graph.h> 
d#Einclude <stdlib.h> 
d#Finclude <conio.h> 


void main( void ) 
{ 
SNOrt- x; Vs 
struct _xycoord xystart, xyend, xyfill; 


/* Find a valid graphics mode */ 
if( !_setvideomode( _MAXRESMODE ) ) 
exit( 1 ); 


/* Draw arcs * / 

x = 100; y = 100; 

_arc( x - 60, y - 60, x, y, x - 30, y - 60, x - 60, y - 3@ ); 
_arc( x + 60, y + 60, x, y, x, y + 30, x + 30, y ); 


/* Get endpoints of second arc and enclose the figure, then fill it. */ 
_getarcinfo( &xystart, &xyend, &xyfill ); 

_moveto( xystart.xcoord, xystart.ycoord ); 

_lineto( xyend.xcoord, xyend.ycoord ); 

_floodfill( xyfill.xcoord, xyfill.ycoord, _getcolor() ); 


_getch(); 
_setvideomode( _DEFAULTMODE ); 


ss asctime 


Description 


Remarks 


Return Value 


asctime 


Converts a tm time structure to a character string. 
#include <time.h> 
char *asctime( const struct tm *timeptr ); 


timeptr Time/date structure 


The asctime function converts a time stored as a structure to a character string. 
The timeptr value is usually obtained from a call to gmtime or localtime, both of 
which return a pointer to a tm structure, defined in TIME.H. (See gmtime for a 
complete description of the tm structure fields.) 


The tm structure contains the following elements: 


Element Description 

int tm_sec Seconds after the minute (0-59) 
int tm_min Minutes after the hour (0-59) 
int tm_hour Hours since midnight (0-23) 
int tm_mday Day of the month (0-31) 

int tm_mon Months since January (O—11) 
int tm_year Years since 1900 

int tm_wday Days since Sunday (O—6) 

int tm_yday Days since January 1 (O—365) 
int tm_isdst Daylight-saving-time flag 


The string result produced by asctime contains exactly 26 characters and has the 
form of the following example: 


Wed Jan 02 02:03:55 1980\n\@ 


A 24-hour clock is used. All fields have a constant width. The newline character 
(\n) and the null character (’\0’) occupy the last two positions of the string. The 
asctime function uses a single statically allocated buffer to hold the return string. 
Each call to this routine destroys the result of the previous call. 


The asctime function returns a pointer to the character string result. There is no 
error return. 
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Compatibility Standards: ANSI, UNIX 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 

See Also ctime, _ ftime, gmtime, localtime, time, _ tzset 


Example 


Output 


/* ASCTIME.C: This program places the system time in the long integer aclock, 
* translates it into the structure newtime and then converts it to 

* String form for output, using the asctime function. 

* / 


dFinclude <time.h> 
dFinclude <stdio.h> 


struct tm *newtime; 
time_t aclock; 


void main( void ) 


{ 
time( &aclock ); /* Get time in seconds */ 
newtime = localtime( &aclock ); /* Convert time to struct tm form */ 
/* Print local time as a string */ 
printf( "The current date and time are: %s\n", asctime( newtime ) ); 
} 


The current date and time are: Tue Jun 15 06:57:59 1999 


90 asin Functions 


Description 


Remarks 


Return Value 


Compatibility 


See Also 


asin Functions 


Calculate the arcsine. 


#include <math.h> 


#include <errno.h> 


double asin( double x ); 


long double _ asinl( long double x ); 


x Value whose arcsine is to be calculated 


The asin functions calculate the arcsine of x in the range —1/2 to 1/2 radians. The 
value of x must be between —1 and 1. The _ asinl function is the 80-bit counterpart, 
which uses an 80-bit, 10-byte coprocessor form of arguments and return values. 
See the reference page on the long double functions for more details on this 

data type. 


The asin functions return the arcsine result. If x is less than —1 or greater than 1, 
asin sets errno to EDOM, prints a_ DOMAIN error message to stderr, and re- 
turns 0. 


Error handling can be modified by using the _ matherr (or _matherrl) routine. 


asin 

Standards: ANSI, UNIX 

16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 

_asinl 


Standards: None 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: None 


acos functions, atan functions, cos functions, _ matherr, sin functions, tan 
functions 


Example 


Output 


/* 


* / 


asin Functions 


ASINCOS.C: This program prompts for a value in the range -1 to l. 
Input values outside this range will produce _DOMAIN error messages. 
If a valid value is entered, the program prints the arcsine and the 
arccosine of that value. 


#Finclude <math.h> 

#Hinclude <stdio.h> 
dHinclude <stdlib.h> 
4#FHinclude <errno.h> 


void main( void ) 


{ 


double x, y; 


printf( “Enter a real number between -1 and 1: " ); 
scanf( "%1f", &Xx ); 

y = asin( x ); 

printf( "Arcsine of %f = %f\n", x, y ); 

y = acos( x ); 

printf( “Arccosine of 4f = “f\n", x, y ); 


Enter a real number between -1 and 1: .32696 
Arcsine of 0.326960 = 0.333085 
Arccosine of @.326960 = 1.237711 
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92 assert 


Description 


Remarks 


Return Value 


Compatibility 


See Also 


assert 


Prints an error message and aborts the program. 


#include <assert.h> 


#include <stdio.h> 
void assert( int expression ); 


expression C expression specifying assertion being tested 


The assert routine prints a diagnostic message and calls the abort routine if 
expression 1s false (0). The diagnostic message has the form 


Assertion failed: expression, file filename, line linenumber 


where filename is the name of the source file and Jinenumber is the line number of 
the assertion that failed in the source file. No action is taken if expression is true 
(nonzero). 


In Windows, the diagnostic message appears in an “Assertion Failed” pop-up 
window. 


The assert routine is typically used in program development to identify program 
logic errors. The given expression should be chosen so that it holds true only if the 
program is operating as intended. After a program has been debugged, the special 
“no debug” identifier NDEBUG can be used to remove assert calls from the pro- 
gram. If NDEBUG is defined (by any value) with a /D command-line option or 
with a #define directive, the C preprocessor removes all assert calls from the pro- 
gram source. 


The assert routine is implemented as a macro. 


None. 


Standards: ANSI, UNIX 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 


abort, raise, signal 


Example 


Output 


assert 


/* ASSERT.C: In this program, the analyze_string function uses the 
* assert function to test several conditions related to string and 
* length. If any of the conditions fails, the program prints a 
* message indicating what caused the failure. 

* / 


4#FAinclude <stdio.h> 
#Finclude <assert.h> 
dHinclude <string.h> 


void analyze_string( char *string ); /* Prototype */ 


void main( void ) 
{ 
char: testif] = “abc™, *test2 = NULL, “test3i} ="; 


printf ( "Analyzing string '%s'\n", testl ); 
analyze _string( testl ); 
printf ¢( "Analyzing string ‘%s'\n", test2 ); 
analyze_string( test2 ); 
printf ( "Analyzing string ‘%s'\n", test3 ); 
analyze_string( test3 ); 

} 


/* Tests a string to see if it is NULL, empty, or longer than @ characters */ 


void analyze_string( char * string ) 
{ 
assert( string != NULL ); /* Cannot be NULL */ 
assert( *string != '\@' ); /* Cannot be empty */ 
assert( strlen( string ) > 2 ); /* Length must be greater than 2 */ 


Analyzing string ‘abc’ 
Analyzing string ‘(null)' 
Assertion failed: string != NULL, file assert.c, line 28 


abnormal program termination 
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_ 94  atan Functions 


Description 


Remarks 


Return Value 


Compatibility 


atan Functions 


Calculate the arctangent of x (atan and _ atanl) and the arctangent of y/x (atan2 
and _atan2]). 


#include <math.h> 


double atan( double x ); 
double atan2( double y, double x ); 
long double _ atanl( long double x ); 


long double _ atan21( long double y, long double x ); 
x,y | Any number | 


The atan family of functions calculates the arctangent of x, and the atan2 family 
of functions calculates the arctangent of y/x. The atan group returns a value in the 
range —1/2 to 1/2 radians, and the atan2 group returns a value in the range —1 to 7 
radians. The atan2 functions use the signs of both arguments to determine the 
quadrant of the return value. The atan2 functions are well defined for every point 
other than the origin, even if x equals O and y does not equal 0. 


The atan family of functions returns the arctangent result. If both arguments of 
atan2 or _ atan2] are 0, the function sets errno to EDOM, prints a_ DOMAIN 
error message to stderr, and returns 0. 


Error handling can be modified by using the _matherr (or _ matherrl) routine. 


atan, atan2 
Standards: ANSI, UNIX 
16-Bit: DOS, QWIN, WIN, WIN DLL 


32-Bit. = DOS32X 


See Also 


Example 


Output 


_atanl, _ atan2]! 

Standards: None 

16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: None 


acos functions, asin functions, cos functions, _matherr, sin functions, tan 


functions 


atan Functions 


/* ATAN.C: This program calculates the arctangent of 1 and -l. */ 


fAinclude <math.h> 
deinclude <stdio.h> 
d#Hinclude <errno.h> 


void main( void ) 
{ 
double: x1. x25--y¥% 


printf( "Enter a real number: " ); 

scanf( "%1f", &xl ); 

y = atan( xl ); 

printf( "Arctangent of 4“f: “f\n", xl, y ); 
printf( "Enter a second real number: " ); 
scanf( "%1f", &x2 ); 

y = atan2( xl, x2 ); 


printf( "Arctangent of %f / %f: %“%f\n", x1, x2, y ); 


Enter a real number: -862.42 

Arctangent of -862.420000: -1.56963/7 

Enter a second real number: 78.5149 

Arctangent of -862.420000 / 78.514900: -1.480006 
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96 atexit, _ fatexit 


atexit, fatexit 


Description Process the specified function at exit. 
#include <stdlib.h> Required only for function declarations 


int atexit( void ( ___cdecl *func )( void ) ); 


int __ far _fatexit( void (___cdecl __ far *func )( void ) ); 


func Function to be called 


Remarks The atexit function is passed the address of a function (func) to be called when the 
program terminates normally. Successive calls to atexit create a register of func- 
tions that are executed in LIFO (last-in-first-out) order. No more than 32 functions 
can be registered with atexit or _ onexit. The functions passed to atexit cannot 
take parameters. 


For DOS32X, atexit and _ onexit use the heap to hold the “register of functions.” 
Thus, the number of functions that can be registered is limited only by heap 
memory. 


The _fatexit function is a far version of atexit; it can be used with any memory 
model. 


Return Value Both atexit and _fatexit return 0 if successful, or a nonzero value if an error oc- 
curs (e.g., if there are already 32 exit functions defined). 


Compatibility atexit 
Standards: ANSI 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 


Use the ANSI-standard atexit function (rather than the similar _ onexit function) 
whenever ANSI portability is desired. 


See Also 


Example 


Output 
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_ fatexit 


Standards: None 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: None 


abort, exit, _ exit, _ onexit 


/* ATEXIT.C: This program pushes four functions onto the stack of functions 
* to be executed when atexit is called. When the program exits, these 

* programs are executed ona “last in, first out" basis. 

* / 


d#Hinclude <stdlib.h> 
dEinclude <stdio.h> 
void fnl( void ), fn2( void ), fn3( void ), fn4( void ); 


void main( void ) 


{ 
atexit( fnl ); 
atexit( fn2 ); 
atexit( fn3 ); 
atexit( fn4 ); 
printf( "This is executed first.\n" ); 
} 
void fnl() 
{ 
printf( "next.\n" ); 
} 
void fn2() 
{ 
printf( "executed " ); 
} 
void fn3() 
{ 
DrINLT(, “1S. 8 
} 
void fn4() 
{ 
printre. "hha s 
} 


This is executed first. 
This is executed next. 
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Description 


Remarks 


atof, atoi, atol, atold 


Convert strings to double (atof), long double (_ atold), integer (atoi), or long 
(atol). 


#include <math.h> atof, _ atold 
#include <stdlib.h> atof, _ atold, atoi, atol 


double atof( const char “string ); 
long double _atold( const char *string ); 
int atoi( const char *string ); 


long atol( const char “string ); 


string String to be converted 


These functions convert a character string to a double-precision floating-point 
value (atof), an integer value (atoi), a long integer value (atol), or a long double 
value (_atold). The input string is a sequence of characters that can be interpreted 
as a numerical value of the specified type. 


The string size that can be handled by the atof or _ atold function is limited to 100 
characters. 


The function stops reading the input string at the first character that it cannot rec- 
ognize as part of a number. This character may be the null character (’\0’) termi- 
nating the string. 


The atof and _atold functions expect string to have the following form: 
[[whitespace]| [sign] [[digits]] [digits] [{d!D le! E}[[sign]]digits]] 


A whitespace consists of space and/or tab characters, which are ignored; sign is 
either plus (+) or minus (—); and digits are one or more decimal digits. If no digits 
appear before the decimal point, at least one must appear after the decimal point. 


The decimal digits may be followed by an exponent, which consists of an intro- 


ductory letter (d, D, e, or E) and an optionally signed decimal integer. 
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The atoi and atol functions do not recognize decimal points or exponents. The 
string argument for these functions has the form 


[[ whitespace] [|sign]|digits 


where whitespace, sign, and digits are exactly as described above for atof. 


Return Value Each function returns the double, long double, int, or long value produced by in- 
terpreting the input characters as a number. The return value is O (for atoi), OL (for 
atol), and 0.0 (for atof and _ atold) if the input cannot be converted to a value of 
that type. The return value is undefined in case of overflow. 


Compatibility atof, atoi, atol 
Standards: ANSI, UNIX 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 
_atold 
Standards: None 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 
See Also _ecvt, _fevt, _ gcvt, strtod 


Example /* ATOF.C: This program shows how numbers stored as strings can be 
* converted to numeric values using the atof, atoi, and atol functions. 
* / 


dEinclude <stdlib.h> 
dFinclude <stdio.h> 


void main( void ) 


char *s; double x; int i; long 1; 

S87. = 2309. 12E=15"¢ /* Test of atof */ 

X= ator’ 6): 

printf( "“atof test: ASCII string: %s\tfloat: RENN 5: Sy. Ke JS 


S "7 .8912654773d210"; /* Test of atof */ 
x atof( s ); 
printf( “atof test: ASCII string: 4s\tfloat: %Ze\n", S, X )3 
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Output 


atof, atoi, atol, atold 


S 2] 
j 


-9885 pigs"; 


avon’ Ss 


printf( "atoi test: 


s = "98854 dollars"; 
1 = atoll -s:); 
printf( "“atol test: 


atof test: 
atof test: 
atoi test: 
atol test: 


ASCII 
ASCII 
ASCII 
ASCII 


string: 
string: 
string: 
string: 


/* Test of atoi */ 


/* Test of atol */ 


98854 dollars 


ASCII string: %s\t\tinteger: %d\n", s, i ); 


ASCII string: %s\t\tlong: WVGNM sy “Se L248 
-2309.12E-15 float: -2.309120e-012 
7.8912654773d210 float: 7 .891265e+210 
-9885 pigs integer: -9885 


long: 98854 


Description 


Remarks 


Return Value 


Compatibility 


See Also 
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_hbdos 
Invokes the DOS system call. 
#include <dos.h> 


int _ bdos( int dosfunc, unsigned int dosdx, unsigned int dosal ); 


dosfunc Function number 
dosdx DX register value 
dosal AL register value 


The _ bdos function invokes the DOS system call specified by dosfunc after 
placing the values specified by dosdx and dosal in the DX and AL registers, 
respectively. The _ bdos function executes an INT 21H instruction to invoke the 
system call. When the system call is complete, _ bdos returns the contents of the 
AX register. 


The _ bdos function is intended to be used to invoke DOS system calls that either 
take no arguments or take arguments only in the DX (DH, DL) and/or AL registers. 


Do not use the _ bdos function to call interrupts that modify the DS register. In- 
stead, use the _intdosx or _ int86x function. The _intdosx and _ int86x functions 
load the DS and ES registers from the segregs argument and also store the DS and 
ES registers into segregs after the function call. 


This call should not be used to invoke system calls that indicate errors by setting 
the carry flag. Since C programs do not have access to this flag, your program can- 
not determine whether the return value is an error code. The _intdos function 
should be used in these cases. 


The _ bdos function returns the value of the AX register after the system call has 
completed. 


Standards: None 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: None 


_intdos, _intdosx 
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Example /* BDOS.C: This example calls DOS function @x9 (display string) 
* to display a $-terminated string. 
* / 


dEinclude <dos.h> 


/* Function @x@9 assumes that DS will contain segment of the string. 
* This will be true for all memory models if the string is declared near. 
* / 

char __near str{] = “Hello world!\r\n$"; 


void main( void ) 
{ 


/* Offset of string must be in DX, segment in DS. AL is not needed, 
* SO @ is used. 
* / 

_bdos( @x@9, (int)str, @ ); 


Output Hello world! 


Description 


Remarks 


Bessel Functions 


Bessel Functions 


Compute the Bessel function. 
#include <math.h> 


double _ j0( double x ); 

double _j1( double x ); 

double _ jn( int n, double x ); 
double _ y0( double x ); 

double _ y1( double x ); 

double _ yn( int n, double x ); 
long double _ j0l( long double x ); 
long double _ jnl( int n, long double x ); 
long double _j1l( long double x ); 
long double _ y0l( long double x ); 
long double _ y1l( long double x ); 


long double _ yni( int n, long double x ); 


Floating-point value 


Integer order 
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The _j0, _j1, and _jn routines return Bessel functions of the first kind—orders 0, 


1, and n, respectively. 


The _y0, _ yl, and _yn routines return Bessel functions of the second kind— 


orders 0, 1, and n, respectively. The argument x must be positive. 
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Return Value 


Compatibility 


See Also 


Example 


The long double versions of these functions are the 80-bit counterparts and use the 
80-bit, 10-byte coprocessor form of arguments and return values. See the reference 
page on the long double functions for more details on this data type. 


The Bessel functions are explained more fully in most mathematics reference 
books, such as the Handbook of Mathematical Functions (Abramowitz and 
Stegun; Washington: U.S. Government Printing Office, 1964). These functions are 
commonly used in the mathematics of electromagnetic wave theory. 


These functions return the result of a Bessel function of x. 


For _ y0, _ yl, or _ yn, if x is negative, the routine sets errno to EDOM, prints a 
_DOMAIN error message to stderr, and returns -HUGE_ VAL. 


Error handling can be modified by using the _ matherr (or _ matherrl) routine. 


_j0, _j1, _jn, yO, _y1, _yn 

Standards: UNIX 

16-Bit: DOS, QWIN, WIN, WIN DLL 

32-Bit: DOS32X 

Use _jO, _j1, _jn, _y0, _y1, and _yn for compatibility with ANSI naming con- 
ventions of non-ANSI functions. Use jo, j1, jn, yO, y1, and yn and link with 
OLDNAMES.LIB for UNIX compatibility. 

_jOl, _jll, _jnl, _y0l, _yll, _ynl 

Standards: None 


16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: None 
_matherr 


/* BESSEL.C: This program illustrates Bessel functions, including: 


_ je _Jjl _jn _y@ _yl _yn 


d#Finclude <math.h> 
#Hinclude <stdio.h> 
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void main( void ) 


{ 
double x = 2.387; 
Tbe 1S Bis -es 
printf( "Bessel functions for x = 4f:\n", x ); 
printf( " Kind\t\tOrder\t\Function\tResult\n\n" ); 
printf( “"  First\t\t@\t_j@( x )\t\t%Zf\n", _j@( x ) ); 
DrIneT CP TEREST NANG oe ONENESS 
for( c= 2; ¢ < 5: ct ) 

PrIMtTG-” RICSEV TNIV ni Ne ke DN AT se - NG es Kes 
printf( " Second\t@\t_y@( x )\t\t%f\n", _y@( x ) ); 
printre * Second\tl\toylt x JCA ny VLC ox: 9s 
for( c = 2: c < 5; cH ) 

printte- " ‘Second\tsdvt. ynG ne xX J\CAT AM"; “Cs. UNG cy ks 

} 
Output Bessel functions for x = 2.387000: 

Kind Order Function Result 
First Q _j@( x ) @.009288 
First 1 _jl( x ) @.522941 
PERS. 2 _jn( n, x ) @.428870 
First 3 _jn( n, x ) @.195734 
First 4 _jn( n, x ) @.063131 
Second Q _y@( x ) @.511681 
Second 1 _yl( x ) Q@.094374 
Second 2 _yn( n, xX ) -@.432608 
Second | _yn( n, X ) -@.819314 
Second 4 _yn( n, Xx ) -1.626833 
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_bfreeseg 


Description Frees a specified based heap. 
#include <malloc.h> Required only for function declarations 
int _bfreeseg( ___ segment seg ); 


seg Segment selected 


Remarks The _bfreeseg function frees a based heap. The seg argument is a based heap re- 
turned by an earlier call to _ bheapseg. It specifies the based heap to be freed. 


_The specified segment is freed completely regardless of whether the blocks it con- 
tains are free or allocated. After a _ bfreeseg call, the seg value is invalid and 
should not be used. 


Return Value The _bfreeseg function returns 0 if successful and —1 in the case of an error. 
Compatibility Standards: None 

16-Bit: DOS, QWIN, WIN, WIN DLL 

32-Bit: None 
See Also _bheapseg, calloc functions, free functions, malloc functions, realloc functions 


Example See the example for _ bheapseg. 


Description 


Remarks 


Return Value 


Compatibility 


See Also 
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_bheapseg 


Allocates a based heap. 
#include <malloc.h> Required only for function declarations 
__segment _ bheapseg( size_t size ); 


size Segment size to allocate 


The _ bheapseg function allocates a based-heap segment of at least size bytes. 
(The block may be larger than size bytes because of space required for alignment 
and for maintenance information. ) 


The value returned by _ bheapseg is the identifier of the based-heap segment. This 
value should be saved and used in subsequent calls to other based-heap functions. 
If the original block of memory is depleted (e.g., by calls to_bmalloc and 
_brealloc), the run-time code will try to enlarge the heap as necessary. 


The _ bheapseg function can be called repeatedly. For each call, the run-time 
library will allocate a new based-heap segment. 


The _ bheapseg function returns the newly allocated segment selector; save this 
value for use in subsequent based-heap functions. A return value of _NULLSEG 
indicates failure. 


Always check the return from the _bheapseg function (especially when it is used 
in real mode), even if the amount of memory requested is small. 


Standards: None 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: None 


calloc functions, free functions, malloc functions, realloc functions 
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Example 


_bheapseg 


/* BHEAPSEG.C: This program C illustrates dynamic allocation of based 
* memory using functions _bheapseg, _bfreeseg, _bmalloc, and _bfree. 
* / 


#Hinclude <stdio.h> 
d#tinclude <malloc.h> 
#Finclude <stdlib.h> 
fHinclude <string.h> 


void main( void ) 

{ 
__ segment seg; ‘ 
char __based( seg ) *outstr, __based( seg ) *instr; 
char __based( seg ) *pout, _based( seg ) *pin; 
char tmpstr[80];_ 
int len; 


printf( "Enter a string: " ); 
gets( tmpstr ); 


/* Request a based heap. Use based so that memory won't be taken from 
* near heap. 
* / 
if( (seg = _bheapseg( 1000 )) == _NULLSEG ) 
exit( 1 ); 


/* Allocate based memory for two strings. */ 
len = strlen( tmpstr ); 


if( (Cinstr = _bmalloc( seg, len + 1 )) == _NULLOFF) || 
(Coutstr = _bmalloc( seg, len + 1 )) == _NULLOFF) ) 
exit( 1 ); | 


/* Copy a lowercased string to dynamic memory. The based memory is 
* far when addressed as a whole. 
* / 

_fstriwr( _fstrcepy( (char __far *)instr, (char __far *)tmpstr ) ); 


/* Copy input string to output string in reversed order. When reading 
* and writing individual characters from a based heap, the compiler will 
* try to process them as near, thus speeding up the processing. 
* / ! 
for( pin = instr + len - 1, pout = outstr; 

: pout < outstr + len; pin--, pout++ ) 

*pout = *pin; 

*pout = '\Q'; 


Output 


/* Display strings. Again, strings as a whole are far. 


printf( "Input: %Fs\n", (char __far *)instr ); 
printf( "Output: “Fs\n", (char __ far *)outstr ); 


/* Free blocks and release based heap. */ 
_bfree( seg, instr ); 

_bfree( seg, outstr ); 

_bfreeseg( seg ); 


Enter a string: Was I god 
Input: was 1 god 
Output: dog i saw 


_bheapseg 


* / 
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110  _bios_ disk 
_ bios_ disk 

Description Calls BIOS disk services, using INT 0x13. 
#include <bios.h> 


unsigned _bios_disk( unsigned service, struct _diskinfo_t “diskinfo ); 


service Disk function desired 
diskinfo Disk parameters 
Remarks The _ bios_ disk routine uses INT 0x13 to provide several disk-access functions. 


The service parameter selects the function desired, while the diskinfo structure pro- 
vides the necessary parameters. Note that the low-level disk operations allowed by 
the _ bios_ disk routine are very dangerous to use because they perform direct 
manipulation of the disk. 


The diskinfo structure provides the following parameters: 


Element Description 

unsigned drive Drive number 

unsigned head Head number 

unsigned track Track number 

unsigned sector Starting sector number 

unsigned nsectors Number of sectors to read, write, or compare 

void far *buffer Memory location to write to, read from, or compare 


The service argument can be set to one of the following manifest constants: 


Constant Function 


_DISK_FORMAT _ Formats the track specified by diskinfo. The head and track 
fields indicate the track to format. Only one track can be 
formatted in a single call. The buffer field points to a set of 
sector markers. The format of the markers depends on the type 
of disk drive; see a technical reference to the PC BIOS to 
determine the marker format. The high-order byte (AH) of the 
return value contains the status of the call; 0 equals success. If 
there is an error, the high-order byte will contain a set of status 
flags, as defined below under Return Value. 


Return Value 


Constant 


_DISK_READ 


_DISK_ RESET 


_DISK_STATUS 


_DISK_ VERIFY 


_DISK_ WRITE 
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Function 


Reads one or more disk sectors into memory. This service uses 
all fields of the structure pointed to by diskinfo, as defined 

earlier in this section. If no error occurs, the function returns O in 
the high-order byte and the number of sectors read in the low- 
order byte. If there is an error, the high-order byte (AH) will 
contain a set of status flags, as defined below under Return Value. 


Forces the disk controller to do a hard reset, preparing for floppy- 
disk I/O. This is useful after an error occurs in another operation, 
such as a read. If this service is specified, the diskinfo argument 
is ignored. Status is returned in the 8 high-order bits (AH) of the 
return value. If there is an error, the high-order byte will contain 
a set of status flags, as defined below under Return Value. 


Obtains the status of the last disk operation. If this service 1s 
specified, the diskinfo argument is ignored. Status 1s returned in 
the 8 low-order bits (AL) of the return value. If there is an error, 
the low-order byte (AL) will contain a set of status flags, as 
defined below under Return Value. 


Checks the disk to be sure the specified sectors exist and can be 
read. It also runs a CRC (cyclic redundancy check) test. This 
service uses all fields (except buffer) of the structure pointed to 
by diskinfo, as defined earlier in this section. If no error occurs, 
the function returns O in the high-order byte (AH) and the 
number of sectors compared in the low-order byte (AL). The 
error status flags are listed below under Return Value. 


Writes data from memory to one or more disk sectors. This 
service uses all fields of the structure pointed to by diskinfo, as 
defined earlier in this section. If no error occurs, the function 
returns 0 in the high-order byte (AH) and the number of sectors 
written in the low-order byte (AL). If there is an error, the high- 
order byte will contain a set of status flags, as defined below 
under Return Value. 


The _ bios_ disk function returns the value in the AX register after the BIOS 


interrupt. 
Bits 
0x00 
Ox01 
Ox02 
Ox03 
0x04 
0x05 
0x06 
0x07 


Meaning 


No error 

Invalid request or a bad command 
Address mark not found 

Disk write protected 

Sector not found 

Reset failed 

Floppy disk removed 

Drive parameter activity failed 
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Bits Meaning 

Ox08 Direct Memory Access (DMA) overrun 

0x09 DMA crossed 64K boundary 

Ox0A Bad sector flag detected 

Ox0B Bad track flag detected 

Ox0C Media type not found 

Ox0D Invalid number of sectors on format 

OxOE Control data access mark detected 

OxOF DMA arbitration level out of range 

Ox10 Data read (CRC or ECC) error 

Ox11 Corrected data read (ECC) error 

0x20 Controller failure 

0x40 Seek error 

Ox80 Disk timed out or failed to respond 

OxAA Drive not ready 

OxBB Undefined error 

OxCC Write fault on drive 

OxEO Status error 

OxFF Sense operation failed 
Compatibility Standards: None 

16-Bit: DOS, QWIN, WIN, WIN DLL 

32-Bit: None 


Example /* BDISK.C: This program first attempts to verify a disk by using an 
* invalid disk head number. After printing the return value error code, 
* the program verifies the disk by using a valid disk head code. 
* / 


d#Finclude <conio.h> 
dAinclude <stdio.h> 
d#Ainclude <bios.h> 


Output 


_bios_ disk 


void main( void ) 


‘ 

unsigned status = Q; 

struct _diskinfo_t disk_info; 

disk_info.drive = Q; 

disk_info.head =a /* Invalid head number */ 

disk_info.track = is 

disk_info.sector =. <7 

disk_info.nsectors = 8; 

printf( "Insert disk in drive A: and press any key\n" ); 

_getch(); 

status = _bios_disk( _DISK VERIFY, &disk_info ); 

printf( "Return value: @x%.4x\n", status ); 

if( status & Oxff@@ ) /* Error if high byte is Q */ 
printf( "Seek error\n" ); 

else 
printf( "No seek error\n" ); 

printf( "Press any key\n" ); 

_getch(); 

disk_info.head = @; /* Valid head number */ 

status = _bios_disk( _DISK_VERIFY, &disk_info ); 

printf( “Return value: @x%.4x\n", status ); 

if( status & @xff@@ ) /* Error if high byte is @ */ 
printf( "Seek error\n" ); 

else 
printf( "No seek error\n" ); 

} 


Insert disk in drive A: and press any key 
Return value: @x@400 

Seek error 

Press any key 

Return value: @x@0Q08 

No seek error 
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114 _bios_equiplist 
_bios_ equiplist 

Description Calls BIOS equipment-list service, using INT 0x11. 
#include <bios.h> 


unsigned _ bios_ equiplist( void ); 


Remarks The _ bios_ equiplist routine uses INT 0x11 to determine what hardware and 
peripherals are currently installed on the machine. 


Return Value The function returns the AX value, which is a set of bits indicating what equip- 
ment is installed, as defined below: 
Bits Meaning 
0 True (1) if disk drive(s) installed 
1 True (1) if math coprocessor installed 
2-3 System RAM in 16K blocks (16-64K) 
4-5 Initial video mode: 


OO = Reserved 

01 = 40 x 25 color 

10 = 80 x 25 color 

11 = 80 x 25 monochrome 


6-7 Number of floppy-disk drives installed (00 = 1, 01 = 2, etc.) 
8 False (0) if and only if a Direct Memory Access (DMA) chip is 
installed 
9-1] Number of RS232 serial ports installed 
12 True (1) if and only if a game adapter is installed 
13 True (1) if and only if an internal modem is installed 
14-15 Number of printers installed 
Compatibility Standards: None 
16-Bit: DOS, QWIN, WIN, WIN DLL 


32-Bit: None 


Example 


Output 


_bios_ equiplist 


/* BEQUIPLI.C: This program checks for the presence of diskettes. */ 


deinclude <bios.h> 
dEinclude <stdio.h> 


void main( void ) 
{ 
unsigned equipment; 


equipment = _bios_equiplist(); 

printf( "Equipment bits: @x%.4x\n", equipment ); 

if( equipment & @x100Q0 ) /* Check for game adapter bit */ 
printf( "Game adapter installed\n" ); 

else 
printf( "No game adapter installed\n" ); 


Equipment bits: @x4061 
No game adapter installed 
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116  _bios_keybrd 
_bios_keybrd 

Description Calls BIOS keyboard services, using INT 0x16. 
#include <bios.h> 


unsigned _ bios_keybrd( unsigned service ); 


service Keyboard function desired 

Remarks The _ bios_keybrd routine uses INT 0x16 to access the keyboard services. The 
service argument can be any of the following manifest constants: 
Constant Meaning 
_KEYBRD_ READ, Reads the next character from the keyboard. If no 
_NKEYBRD_READ character has been typed, the call will wait for 


one. If the low-order byte of the return value is 
nonzero, the call contains the ASCII value of the 
character typed. The high-order byte contains the 
keyboard scan code for the character. The 
_NKEYBRD_READ constant is used with 
enhanced keyboards to obtain the scan codes for 
function keys F11 and F12 and the cursor control 


keys. 
_KEYBRD_READY, Checks whether a keystroke 1s waiting to be read 
_NKEYBRD_READY and, if so, reads it. The return value is 0 if no 


keystroke is waiting, or it is the character waiting 
to be read, in the same format as the 
_KEYBRD_ READ or _NKEYBRD_READ 
return. This service does not remove the waiting 
character from the input buffer, as does the 
—_KEYBRD_ READ or _NKEYBRD_ READ 
service. The _NKEYBRD_ READY constant is 
used with enhanced keyboards to obtain the scan 
codes for function keys F11 and F12 and the 
cursor control keys. 


Return Value 


Compatibility 
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Constant Meaning 
_KEYBRD_SHIFTSTATUS, Returns the current SHIFT-key status. 
_NKEYBRD_SHIFTSTATUS _KEYBRD_SHIFTSTATUS returns only low 


byte. The NKEYBRD_SHIFTSTATUS 
constant is used to get a full 16-bit status value. 
Any combination of the following bits may be set: 


Bit Meaning if True 

OOH Rightmost SHIFT key pressed 
01H Leftmost SHIFT key pressed 
02H Either CTRL key pressed 
3H Either ALT key pressed 
04H SCROLL LOCK on 

05H NUM LOCK on 

06H CAPS LOCK on 

07H In insert mode (INS) 

08H Left CTRL key pressed 

O9H Left ALT key pressed 

OAH Right CTRL key pressed 
OBH Right ALT key pressed 

OCH SCROLL LOCK key pressed 
ODH NUM LOCK key pressed 
OEH CAPS LOCK key pressed 
OFH SYS REQ key pressed 


With the ... READ and ..SHIFTSTATUS arguments, the _ bios_ keybrd function 
returns the contents of the AX register after the BIOS call. 


With the .. READY argument, _ bios_keybrd returns 0 if there is no key. If there 
is a key, _bios_keybrd returns the key waiting to be read (1.e., the same value as 
_KEYBRD_ READ). 


With the ... READ and the .. READY arguments, the _ bios_keybrd function re- 
turns —1 if CTRL+BREAK has been pressed and is the next keystroke to be read. 


Standards: None 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: None 
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Example /* BKEYBRD.C: This program prints a message on the screen until the 
~* right SHIFT key is pressed. 
* / 


4Ainclude <bios.h> 
d#Ainclude <stdio.h> 


void main( void ) 


{ 
while( !(_bios_keybrd( _KEYBRD_SHIFTSTATUS ) & @@@1) ) 
printf( "Use the right SHIFT key to stop this message\n" ); 
printf( "Right SHIFT key pressed\n" ); 
} 
Output Use the right SHIFT key to stop this message 


Use the right SHIFT key to stop this message 
Use the right SHIFT key to stop this message 
Use the right SHIFT key to stop this message 
Right SHIFT key pressed 
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_ bioS_ memsize 


Description Calls the BIOS memory-size service, using INT 0x12. 
#include <bios.h> 
unsigned _ bios_memsize( void ); 

Remarks The _ bios_memsize routine uses INT 0x12 to determine the total amount of main 
memory installed. 

Return Value The routine returns the total amount of installed memory in 1K blocks. The maxi- 
mum return value is 640, representing 640K of main memory. 

Compatibility Standards: None 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: None 

Example /* BMEMSIZE.C: This program displays the amount of memory installed. */ 


Output 


dFinclude <bios.h> 
dFinclude <stdio.h> 


void main( void ) 
{ 


unsigned memory; 


memory = _bios_memsize(); 
printf ( “The amount of memory installed is: %dK\n", memory ); 


The amount of memory installed is: 640K 
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Description 


Remarks 


Return Value 


_bios_ printer 


Calls BIOS printer services, using INT 0x17. 
#include <bios.h> 


unsigned _ bios_ printer( unsigned service, unsigned printer, unsigned data ); 


service Printer function desired 
printer Target printer port 
data Output data 


The _bios_ printer routine uses INT 0x17 to perform printer output services for 
parallel printers. The printer argument specifies the affected printer, where 0 is 
LPT1, 1 is LPT2, and so forth. 


Some printers do not support the full set of signals. As a result, the “Out of Paper’ 
condition, for example, may not be returned to your program. 


The service argument can be any of the following manifest constants: 


Constant Meaning 

_PRINTER_INIT Initializes the selected printer. The data argument is 
ignored. 

_PRINTER_STATUS Returns the printer status. The data argument is ignored. 

_PRINTER_WRITE Sends the low-order byte of data to the printer specified 
by printer. 


The _ bios_ printer function returns the value in the AX register after the BIOS in- 
terrupt. The high-order byte (AH) of the return value indicates the printer status 
after the operation, as defined below: 


Bit Meaning if True Bit Meaning if True 
0 Printer timed out 4 Printer selected 

] Not used 5 Out of paper 

2 Not used 6 Acknowledge 

3 I/O error ii Printer not busy 


Compatibility 


Example 


Output 
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Standards: None 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: None 


/* BPRINTER.C: This program checks the status of the printer attached to 
* LPT1 when it is off line, then initializes the printer. 
* / 


d4Finclude <bios.h> 
dEinclude <conio.h> 
dFinclude <stdio.h> 


dtdefine LPT1 Q 


void main( void ) 
{ 
unsigned status; 


printf ( "Place printer off line and press any key\n" ); 
Getcnt)s 


status = _bios_printer( _PRINTER_STATUS, LPT1, @ ); 

printf( "Status with printer off line: 0x%.4x\n\n", status ); 
printf( "Put the printer on line and then\n" ); 

printf( "Press any key to initialize printer\n" ); 

_getch(); 


Status = _bios_printer( _PRINTER_INIT, LPT1, Q ); 
printf( "Status after printer initialized: 0x%.4x\n", status ); 


Place printer off line and press any key 
Status with printer off line: @x@018 


Put the printer on line and then 
Press any key to initialize printer 
Status after printer initialized: 0@x0090 
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Description 


Remarks 


_ bios serialcom 


Calls BIOS communications services, using INT 0x14. 
#include <bios.h> 


unsigned _ bios_serialcom( unsigned service, unsigned serial_port, 
unsigned data ); 


service Communications service 
serial_port Serial port to use 
data Port configuration bits 


The _ bios_serialcom routine uses INT 0x14 to provide serial communications 
services. The serial_port argument is set to 0 for COM1, to 1 for COM2, and 
So on. | 


The _ bios_serialcom routine may not be able to establish reliable communica- 
tions at baud rates in excess of 1,200 baud (__COML_ 1200) due to the overhead 
associated with servicing computer interrupts. Faster data communication rates 
are possible with more direct programming of serial-port controllers. See 

C Programmer’s Guide to Serial Communications for more details on serial- 
communications programming in C. 


The service argument can be set to one of the following manifest constants: 


Constant Service 

_COM_ INIT Sets the port to the parameters specified in the data 
argument 

_COM_SEND Transmits the data characters over the selected serial port 

_COM_ RECEIVE Accepts an input character from the selected serial port 


_COM_STATUS Returns the current status of the selected serial port 


Return Value 


_bios_serialcom 


The data argument is ignored if service is set to__COM_ RECEIVE or 
_COM_STATUS. The data argument for _COM_INIT is created by combining 
(with the OR operator) one or more of the following constants: 


Constant Meaning 
_COM_CHR7 7 data bits 
_COM_CHR8 8 data bits 
_COM_STOP1 1 stop bit 
_COM_STOP2 2 stop bits 
_COM_NOPARITY No parity 


_COM_EVENPARITY Even parity 
_COM_ODDPARITY Odd parity 


_COM_ 110 
_COM_ 150 
_COM_ 300 
_COM_ 600 
_COM_ 1200 
_COM_ 2400 
_COM_ 4800 
—_COM_9600 


110 baud 
150 baud 
300 baud 
600 baud 
1,200 baud 
2,400 baud 
4,800 baud 
9,600 baud 


The default value of data is 1 stop bit, no parity, and 110 baud. 


The function returns a 16-bit integer whose high-order byte contains status bits. 


The meaning of the low-order byte varies, depending on the service value. The 
high-order bits have the following meanings: 


Bit 
15 
14 
13 
12 
11 
10 


Meaning if Set 


Timed out 

Transmission-shift register empty 
Transmission-hold register empty 
Break detected 

Framing error 

Parity error 

Overrun error 

Data ready 


When service is _COM_SEND, bit 15 will be set if data could not be sent. 
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When service is_COM_ RECEIVE, the byte read will be returned in the low- 
order bits if the call is successful. If an error occurs, any of the bits 9, 10, 11, or 15 
will be set. 


When service is _COM_INIT or _COM_STATUS, the low-order bits are de- 
fined as follows: 


Bit Meaning if Set 
7 Receive-line signal detected 
6 Ring indicator 
5 Data set ready 
4 _ Clear to send 
3 Change in receive-line signal detected 
2 Trailing-edge ring indicator 
] Change in data-set-ready status 
0 Change in clear-to-send status 
Note that this function works only with IBM personal computers and true 
compatibles. 
Compatibility Standards: None 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: None 


Example /* BSERIALC.C: This program checks the status of serial port COM1. */ 


#Hinclude <bios.h> 
dHinclude <stdio.h> 


void main( void ) 


if 
unsigned coml_status; 
coml_status = _bios_serialcom( _COM_STATUS, @, @ ); 
printf ( "COM1 status: @x%.4x\n", coml_status ); 

} 


Output COM1 status: 0x6000 
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_ bios_timeofday 
Description Calls BIOS time and date services, using INT Ox1A. 
#include <bios.h> 


unsigned _ bios_timeofday( unsigned service, long *timeval ); 


service Time function desired 
timeval Clock count 
Remarks The _ bios_ timeofday routine uses INT Ox1A to get or set the clock count. The 


service argument can be either of the following manifest constants: 


Constant Meaning 


_TIME_GETCLOCK Copies the current value of the clock count to the 
location pointed to by timeval. If midnight has not passed 
since the last time the system clock was read or set, the 
function returns 0; otherwise, the function returns 1. 


_TIME_SETCLOCK Sets the current value of the system clock to the value in 
the location pointed to by timeval. There is no return 
value. 
Return Value The _ bios_timeofday function returns the value in the AX register after the BIOS 
interrupt. 
Compatibility Standards: None 
16-Bit: DOS, QWIN, WIN, WIN DLL 


32-Bit: None 
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Example /x BTIMEOFD.C: This program gets the current system clock count before and after 
* a "do-nothing"™ loop and displays the difference. 
* / 


#Hinclude <bios.h> 
dFinclude <stdio.h> 


void main( void ) 


{ 
long i, begin_tick, end_tick; 
_bios_timeofday( _TIME_GETCLOCK, &begin_tick ); 
printf( "Beginning tick count: %4lu\n", begin_tick ); 
for( i = 1; i <= 900000; i++ ) 
_bios_timeofday( _TIME_GETCLOCK, &end_tick ); 
printf( "Ending tick count: %1lu\n", end_tick ); 
printf( "Elapsed ticks: *Zlu\n", end_tick - begin_tick ); 

} 

Output Beginning tick count: 1114255 
Ending tick count: 1114287 


Elapsed ticks: 3c 


Description 


Remarks 
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bsearch 


Performs a binary search of a sorted array. 


#include <stdlib.h> Required for ANSI compatibility 


#include <search.h> Required only for function declarations 


void *bsearch( const void *key, const void *base, size_t num, size_t width, 
int (___cdecl *compare )( const void *elem1/, const void *elem2 ) ); 


key Object to search for 

base Pointer to base of search data 

num Number of elements | 

width Width of elements 

compare Function that compares two elements: elem/ and 
elem2 

elem Pointer to the key for the search 

elem2 Pointer to the array element to be compared with 
the key 


The bsearch function performs a binary search of a sorted array of num elements, 
each of width bytes in size. The base value is a pointer to the base of the array to 
be searched, and key is the value being sought. 


The compare argument is a pointer to a user-supplied routine that compares two 
array elements and returns a value specifying their relationship. The bsearch func- 
tion calls the compare routine one or more times during the search, passing point- 
ers to two array elements on each call. The routine compares the elements, then 
returns one of the following values: 


Value Meaning 

<0 elem! less than elem2 
=) elem! identical to elem2 
>0 elem! greater than elem2 


If the array you are searching is not in ascending sort order, bsearch does not 
work properly. If the array contains duplicate records with identical keys, there is 
no way to predict which of the duplicate records will be located by bsearch. 
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Return Value The bsearch function returns a pointer to an occurrence of key in the array pointed 
to by base. If key is not found, the function returns NULL. 


Compatibility Standards: ANSI, UNIX 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 

See Also _Ifind, _lsearch, qsort 


Example /* BSEARCH.C: This program reads the command-line arguments, sorting them 
* with qsort, and then uses bsearch to find the word “cat.” 
* / 


d#Ainclude <search.h> 
dinclude <string.h> 
d#Finclude <stdio.h> 


int compare( char **argl, char **arg2 ); /* Declare a function for compare */ 


void main( int argc, char **argv ) 
{ 

char **result; 

char *key = "cat"; 

int i; 


/* Sort using Quicksort algorithm: */ 
qsort( (char *)argv, argc, sizeof( char * ), compare ); 


for( i = 0; i < argc; ++i ) /* Output sorted list */ 
printf( "4s ", argvLli] ); 


/* Find the word "cat" using a binary search algorithm: */ 
result = (char **)bsearch( (char *) &key, (char *)argv, argc, 
sizeof( char * ), compare ); 
if( result ) 
printf( "\n%s found at %Fp\n", *result, result ); 
else 
printf( "\nCat not found! \n" ); 
} 


int compare( char **argl, char **arg2 ) 
{ 
/* Compare all of both strings: */ 
return _strcmpi( *argl, *arg2 ); 


Output [C:\LIBREF] bsearch dog pig horse cat human rat cow goat 
bsearch cat cow dog goat horse human pig rat 
cat found at 0292:0FDQ@ 


Description 


Remarks 


Return Value 


Compatibility 
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_cabs, _cabsl 


Calculate the absolute value of a complex number. 
#include <math.h> 


double _ cabs( struct _ complex z ); 


long double _ cabsl( struct _ complex! z ); 


Ve Complex number 


The _ cabs and _ cabsl functions calculate the absolute value of a complex num- 
ber, which must be a structure of type _ complex (or _ complexl). The structure z 
is composed of a real component x and an imaginary component y. A call to one of 
the _ cabs routines is equivalent to the following: 


sqrt( z.x*z.x + z.y*z.y ) 


The _ cabsl function is the 80-bit counterpart and it uses the 80-bit, 10-byte co- 
processor form of arguments and return values. See the reference page on the long 
double functions for more details on this data type. 


On overflow, these functions call _matherr or _matherrl, return HUGE_ VAL, 
and set errno to ERANGE. 


_cabs 

Standards: UNIX 

16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 


Use _ cabs for compatibility with ANSI naming conventions of non-ANSI func- 
tions. Use cabs and link with OLDNAMES.LIB for UNIX compatibility. 
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_cabsl 


Standards: None 


16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: None 
See Also abs, fabs, labs 


Example /* CABS.C: Using _cabs, this program calculates the absolute value of 
* a complex number. 
* / 


d#Einclude <math.h> 
dEinclude <stdio.h> 


void main( void ) 

{ 
struct _complex number = { 3.0, 4.0 }; 
double d; 


d = _cabs( number ); 


printf( "The absolute value of 4f + “fi is %f\n", 
number.x, number.y, d ); 


Output The absolute value of 3.000000 + 4.0000001 is 5.000000 


Description 


Remarks 


Return Value 
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calloc Functions 


Allocate an array in memory with elements initialized to 0. 


#include <stdlib.h> For ANSI compatibility (calloc only) 


#include <malloc.h> Required only for function declarations 


void *calloc( size_t num, size_t size ); 
void __ based( void ) *_bcalloc( __ segment seg, size_t num, size_t size )5 
void __ far *_fcalloc( size_t num, size_t size ); 


void __ near *_ncalloc( size_t num, size_t size ); 


num Number of elements 
SIZE Length in bytes of each element 
seg Segment selector 


The calloc family of functions allocates storage space for an array of num ele- 
ments, each of length size bytes. Each element is initialized to 0. 


In large data models (compact-, large-, and huge-model programs), calloc maps 
to _fcalloc. In smal] data models (tiny-, small-, and medium-model programs), 
calloc maps to _ncalloc. 


The various calloc functions allocate storage space in the data segments shown in 
the list below: 


Function Data Segment 

calloc Depends on data model of program 

_bealloc Based heap, specified by seg segment selector 
_fcalloc Far heap (outside default data segment) 
_nealloc Near heap (inside default data segment) 


The calloc functions return a pointer to the allocated space. The storage space 
pointed to by the return value is guaranteed to be suitably aligned for storage of 
any type of object. To get a pointer to a type other than void, use a type cast on the 
return value. 
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The _fcalloc and _ncalloc functions return NULL if there is insufficient memory 
available. The _ bealloc function returns _NULLOFF in this case. 


Compatibility calloc 
Standards: ANSI, UNIX 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 


_bealloc, _ fcalloc, _ ncalloc 


Standards: None 


16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: None 
See Also free functions, _ halloc, _ hfree, malloc functions, realloc functions 


Example /* CALLOC.C: This program uses calloc to allocate space for 4@ long integers. 
* It initializes each element to zero. 
* / 


dEinclude <stdio.h> 
dEinclude <malloc.h> 


void main( void ) 


{ 
long *buffer; 
buffer = (long *)calloc( 40, sizeof( long ) ); 
if( buffer != NULL ) 
printf( "Allocated 4@ long integers\n" ); 
else 
printt( "Can't atiocate memory\n” ); 
free( buffer ); 
} 


Output Allocated 4@ long integers 
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ceil, _ceill 


Description Calculate the ceiling of a value. 
#include <math.h> 


double ceil( double x ); 


long double _ ceill( long double x ); 


x Floating-point value 


Remarks The ceil and _ ceill functions return a double (or long double) value representing 
the smallest integer that is greater than or equal to x. 


The _ ceill function is the 80-bit counterpart and it uses the 80-bit, 10-byte co- 
processor form of arguments and return values. See the reference page on the long 
double functions for more details on this data type. 


Return Value These functions return the double or long double result. There 1s no error return. 
Compatibility ceil 

Standards: ANSI, UNIX 

16-Bit: DOS, QWIN, WIN, WIN DLL 

32-Bit: DOS32X 

_ceill 


Standards: None 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: None 


See Also floor, fmod 
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Example /* FLOOR.C: This example displays the largest integers less than or equal 
* to the floating-point values 2.8 and -2.8. It then shows the smallest 
* integers greater than or equal to 2.8 and -2.8. 
a / 


d#Finclude <math.h> 
#Hinclude <stdio.h> 


void main( void ) 


{ 
double y; 
y = floor( 2.8 ); 
printf( "The floor of 2.8 is %f\n", y ); 
y= TLo0orc =2.8 33 
printf( "The floor of -2.8 is “f\n", y ); 
y=] cer 2.8" De 
printf( "The ceil of 2.8 is %4f\n", y ); 
y = ceil( -2.8 ); 
printf( "The ceil of -2.8 is 4f\n", y ); 

} 

Output The floor of 2.8 is 2.000000 


The floor of -2.8 is -3.000000 
The ceil of 2.8 is 3.000000 
The ceil of -2.8 is -2.000000 


_cexit, c_ exit 135 


_cexit, c_ exit 


Description Perform cleanup operations and return without terminating the process. 
#include <process.h> 


void _cexit( void ); 


void _ c_exit( void ); 


Remarks The _ cexit function calls, in LIFO (“last in, first out’’) order, the functions regis- 
tered by atexit and _ onexit. Then the _ cexit function flushes all I/O buffers and 
closes all open streams before returning. 


The _c_exit function is the same as the _ exit function but returns to the calling 
process without processing atexit or _ onexit or flushing stream buffers. 


The behavior of the exit, _ exit, _ cexit, and _c_exit functions is described in the 
following list: 


Function Action 
exit Performs complete C library termination procedures, terminates 
the process, and exits with the supplied status code 


_ exit Performs “‘quick” C library termination procedures, terminates 
the process, and exits with the supplied status code 


_cexit Performs complete C library termination procedures and returns 
to caller, but does not terminate the process 


_c_exit Performs “quick” C library termination procedures and returns 
to caller, but does not terminate the process 


Return Value None. 

Compatibility Standards: None 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 


See Also abort, atexit, _ exec functions, exit, _ onexit, _ spawn functions, system 
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Description 


Remarks 


Return Value 


Compatibility 


See Also 


_cgets 


Gets a character string from the console. 

#include <conio.h> Required only for function declarations 
char *_cgets( char *buffer ); 

buffer Storage location for data 


The _cgets function reads a string of characters directly from the console and 
stores the string and its length in the location pointed to by buffer. The buffer 
argument must be a pointer to a character array. The first element of the array, 
buffer[O], must contain the maximum length (in characters) of the string to be 
read. The array must contain enough elements to hold the string, a terminating null 
character (’\0’), and two additional bytes. 


The _ cgets function continues to read characters until a carriage-return—line-feed 
(CR-LF) combination is read, or the specified number of characters is read. The 
string is stored starting at str[2]. If a CR-LF combination is read, it is replaced 
with a null character (’\0’) before being stored. The _ cgets function then stores the 
actual length of the string in the second array element, buffer[1]. 


Because all DOS editing keys are active when you call _ cgets, pressing F3 repeats 
the last entry. 


The _cgets function returns a pointer to the start of the string, at buffer[2]. There 
is no error return. 


Standards: None 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 


_getch, _ getche 
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Example /* CGETS.C: This program creates a buffer and initializes the first byte 
* to the size of the buffer - 2. Next, the program accepts an input string 
* using _cgets and displays the size and text of that string. 
* / 


d#Finclude <conio.h> 
d#Ainclude <stdio.h> 


void main( void ) 


{ 
char buffer[82] = { 80 }; /* Maximum characters in first byte */ 
char *result; 
printf( “Input line of text, followed by carriage return:\n"); 
result = _cgets( buffer ); /* Input a line of text */ 
printf( "\nLine length = %4d\nText = 4s\n", buffer[L1l], result ); 

} 

Output Input line of text, followed by carriage return: 


This iS some text 
Line length = 17 
Text = This is some text 
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Description 


Remarks 


_chain_ intr 


Chains an interrupt from one handler to another. 
#include <dos.h> 
void _ chain_ intr( void( __ cdecl __ interrupt __ far “target )( )); 


target Target interrupt routine 


The _ chain_intr routine passes control from one interrupt handler to another. The 
stack and the registers of the first routine are passed to the second, allowing the 
second routine to return as if it had been called directly. 


The _ chain_ intr routine is generally used when a user-defined interrupt handler 
begins processing, then chains to the original interrupt handler to finish processing. 


Chaining is one of two techniques, listed below, that can be used to transfer con- 
trol from a new interrupt routine to an old one: 


= Call _chain_intr with the interrupt routine as an argument. Do this if your 
routine is finished and you want the second interrupt routine to terminate the in- 
terrupt call. 


void __interrupt new_int( unsigned _es, unsigned _ds, 


unsigned _di, unsigned _si,... ) 
{ 
+ O13 /* Initial processing here */ 
_chain_intr( old_int ); /* New DI passed to old_int */ 
age 0 ie /* This is never executed  / 
} 


= Call the interrupt routine (after casting it to an interrupt function if necessary). 
Do this if you need to do further processing after the second interrupt routine 
finishes. 


void __interrupt new_int( unsigned _es, unsigned _ds, 


unsigned _di, unsigned _si,... ) 
A: 
++ di1* /* Initial processing here */ 
(*old_int)(); /* New DI passed to old_int */ 
__asm mov _di, di /* Put real DI from old_int */ 
/* into _di for return * / 


Return Value 


Compatibility 


See Also 
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Note that the real registers set by the old interrupt function are not automatically 
Set to the pseudoregisters of the new routine. 


Use the _ chain_intr function when you do not want to replace the default inter- 
rupt handler, but you do need to see its input. An example is a TSR (terminate-and- 
stay-resident) program that checks all keyboard input for a particular “hot key” 
sequence. 


The _ chain_intr function should be used only with C functions that have been de- 
clared with __interrupt. The __ interrupt declaration ensures that the proce- 
dure’s entry/exit sequence is appropriate for an interrupt handler. 


The _chain_ intr function does not return to the caller. 


Standards: None 
16-Bit: DOS 
32-Bit: None 


_dos_getvect, _dos_keep, — dos_setvect 
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Description 


Remarks 


Return Value 


_chdir 


Changes the current working directory. 


#include <direct.h> Required only for function declarations 


#include <errno.h> Required for errno constants 
int _chdir( char *dirname ); 


dirname Path name of new working directory 


The _ chdir function changes the current working directory to the directory 
specified by dirname. The dirname argument must refer to an existing directory. 


This function can change the current working directory on any drive; it cannot be 
used to change the default drive itself. For example, if A: is the default drive and 
\BIN is the current working directory, the following call changes the current work- 
ing directory for drive C: 


_chdir("c:\\temp"); 


Notice that you must place two backslashes ( \\ ) in a C string in order to represent 
a single backslash ( \ ); the backslash is the escape character for C strings and 
therefore requires special handling. 


This function call has no apparent immediate effect. However, when the _chdrive 
function is called to change the default drive to C:, the current working directory 
becomes C:\TEMP. 


With DOS, the new directory set by the program becomes the new current work- 
ing directory. 


The _ chdir function returns a value of 0 if the working directory is successfully 
changed. A return value of —1 indicates an error, in which case errno is set to 
ENOENT, indicating that the specified path name could not be found. 
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Compatibility Standards: UNIX 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 


See Also 


Example 


Output 


Use _ chdir for compatibility with ANSI naming conventions of non-ANSI func- 
tions. Use chdir and link with OLDNAMES.LIB for UNIX compatibility. 


_dos_setdrive, _mkdir, _ rmdir, system 


/* CHGDIR.C: This program uses the _chdir function to verify that a 

* given directory exists. Under real mode that directory also becomes 
* the current directory. Under protected mode, it is only the default 
* directory for the current process. 

* / 


dFinclude <direct.h> 
d#Hinclude <stdio.h> 
dFinclude <stdlib.h> 


void main( int argc, char *argv[] ) 


{ 
if¢..chdirt. argv[1] > ) 
printf( "Unable to locate the directory: %s\n", argv[1] ); 
else 
system( "dir *.c" ); 
‘ 


[C:\LIBREF] chgdir \tmp 


The volume label in drive C is ZEPPELIN. 
Directory of C:\TMP 


DUP C 232 4-18-99 11:18a 
FEO G 713 4-07-98 2:49p 
2 File(s) 14155776 bytes free 
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Description 


Remarks 


Return Value 


Compatibility 


See Also 


_ chdrive 


Changes the current working drive. 
#include <direct.h> Required only for function declarations 
int _ chdrive( int drive ); 


drive Number of new working drive 


The _ chdrive function changes the current working drive to the drive specified by 
drive. The drive argument uses an integer to specify the new working drive (1=A, 
2=B, etc.). 


This function changes only the working drive; the _ chdir function changes the 
working directory. 


With DOS, the new drive set by the program becomes the new working drive. 


The _ chdrive function returns a value of 0 if the working drive is successfully 
changed. A return value of —1 indicates an error. 


Standards: None 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 


_chdir, _dos_setdrive, _fullpath, _getcwd, _getdrive, _ mkdir, _ rmdir, 
system 


Example /* GETDRIVE.C illustrates drive functions including: 


* 
* / 


_getdrive _chdrive _getdcwd 


#Hinclude <stdio.h> ’ 
#Hinclude <conio.h> 
#Hinclude <direct.h> 
#Hinclude <stdlib.h> 


Output 


void main( void ) 
{ 


int ch, drive, curdrive; 
Static char pathL_MAX_PATH]; 


/* Save current drive. */ 
curdrive = _getdrive(); 


printf( "Available drives are: \n" ); 


/* If we can switch to the drive, it exists. 


for( drive = 1; drive <= 26; drivet+t ) 
if( !_chdrive( drive ) ) 
PrINCrKe "268". EGrivewe: TA ws I Os 


while( 1 ) 
{ 


_chdrive 


printf( “\nType drive letter to check or ESC to quit: " ); 
ch = _getch(); 
if( ch == 27 ) 


break; 


if( isalpha( ch ) ) 
_putch( ch ); 


if( _getdcwd( toupper( ch ) - 'A' + 1, path, _MAX_PATH ) 


!= NULL ) 


printf( “\nCurrent directory on that drive is 4s\n", path ); 


} 


/* Restore original drive. This is only necessary for DOS. Under 0S/2 


* the current drive of the calling process is always restored. 


* / 


_chdrive( curdrive ); 


DRTC Me 2) 


Available drives are: 


Aer (Bie Cs 

Type drive letter 
Type drive letter 
Current directory 


Type drive letter 
Current directory 


Type drive letter 


to 
to 
on 


to 
on 


to 


check or ESC to quit: gq 
check or ESC to quit: a 
that drive is A:\ 


check or ESC to quit: c 
that drive is C:\LIBREF 


check or ESC to quit: 
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Description 


Remarks 


Return Value 


_ chmod 


Changes the file-permission settings. 


#include <sys\types.h> 
#include <sys\stat.h> 
#include <errno.h> 


#include <io.h> Required only for function declarations 
int _chmod( char *filename, int pmode ); 


filename Path name of existing file 


pmode Permission setting for file 


The _chmod function changes the permission setting of the file specified by 
filename. The permission setting controls read and write access to the file. The 
constant expression pmode contains one or both of the manifest constants 
_S_IWRITE and _S_TREAD, defined in SYS\STAT.H. Any other values for 
pmode are ignored. When both constants are given, they are joined with the 
bitwise-OR operator (| ). The meaning of the pmode argument is as follows: 


Value Meaning 

_S_IWRITE Writing permitted 
_S_IREAD Reading permitted 
_S_ITREAD |_S_ITWRITE Reading and writing permitted 


If write permission is not given, the file is read-only. Note that all files are always 
readable; it is not possible to give write-only permission. Thus the modes 
_S_ITWRITE and _S_TREAD | _S_IWRITE are equivalent. 


The _ chmod function returns the value 0 if the permission setting is successfully 
changed. A return value of —1 indicates an error; in this case, errno is set to 
ENOENT, indicating that the specified file could not be found. 


Compatibility 


See Also 


Example 


Output 


Standards: UNIX 


16-Bit: 


32-Bit: DOS32X 
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DOS, QWIN, WIN, WIN DLL 


Use _chmod for compatibility with ANSI naming conventions of non-ANSI func- 
tions. Use chmod and link with OLDNAMES.LIB for UNIX compatibility. 


_access, _ creat, _fstat, _open, _ stat 


/* CHMOD.C: This program uses _chmod to change the mode of a file to 


* read-only. 


* / 


dFinclude 
dFinclude 
#tinclude 
dFinclude 
dFinclude 


<sys\types.h> 
<sys\stat.h> 


<io.h> 
<stdio.h> 
<stdlib.h> 


void main( void ) 


{ 


/* Make file read-only: */ 


if¢( _chmod( "CHMOD.C", _S_IREAD ) == 
perror( "File not found\n" ); 


else 


It then attempts to modify the file. 


i 3) 


printf( "Mode changed to read-only\n" ); 
system( “echo /* End of file */ >> CHMOD.C" ); 


/* Change back to read/write: */ 


if€ _chmod( "CHMOD.C", _S_IWRITE ) == -1 ) 


perror( "File not found\n" ); 


else 


printf( "Mode changed to read/write\n" ); 


Mode changed to read-only 
Access denied 
Mode changed to read/write 
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_chsize 
Description Changes the file size. 


#include <io.h> Required only for function declarations 


#include <errno.h> 


int _ chsize( int handle, long size ); 


handle Handle referring to open file 
size New length of file in bytes 
Remarks The _ chsize function extends or truncates the file associated with handle to the 


length specified by size. The file must be open in a mode that permits writing. Null 
characters (’\0’) are appended if the file is extended. If the file is truncated, all data 
from the end of the shortened file to the original length of the file is lost. 


In DOS and Windows, the directory update is done when a file is closed. Con- 
sequently, while a program is running, requests to determine the amount of free | 
disk space may receive inaccurate results. 


Return Value The _ chsize function returns the value 0 if the file size is successfully changed. A 
return value of —1 indicates an error, and errno is set to one of the following 
values: 

Value Meaning 

EACCES Specified file is locked against access. 

EBADF Specified file is read-only or an invalid file handle. 
ENOSPC No space is left on device. 

Compatibility Standards: UNIX 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 


Use _chsize for compatibility with ANSI naming conventions of non-ANSI func- 
tions. Use chsize and link with OLDNAMES.LIB for UNIX compatibility. 


See Also _close, _ creat, _ open 
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Example /* CHSIZE.C: This program uses _filelength to report the size of a 
* file before and after modifying it with _chsize. 
* / 


#Hinclude <io.h> 
#Finclude <fcntl.h> 
#Hinclude <sys\types.h> 
4#FAinclude <sys\stat.h> 
#Hinclude <stdio.h> 


void main( void ) 


{ 
int fh, result; 
unsigned int nbytes = BUFSIZ; 
/* Open a file */ 
if( (fh = _open( "data", O_RDWR | _O_CREAT, _S_IREAD | _S_IWRITE )) != -1 ) 
{ 
printf( "File length before: %ld\n", _filelength( fh ) ); 
if( _chsize( fh, 329678 ) == @ ) 
printf( "Size successfully changed\n" ); 
else 
printf( "Problem in changing the size\n" ); 
printf( "File length after: %ld\n", _filelength( fh ) ); 
2eloset. Th.) 
} 
I 
Output File length before: @ 


Size successfully changed 
File length after: 329678 
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Description 


Remarks 


Return Value 


Compatibility 


See Also 


_ clear87 


Gets and clears the floating-point status word. 
#include <float.h> 


unsigned int _ clear87( void ); 


The _ clear87 function gets and clears the floating-point status word. The floating- 
point status word is a combination of the 8087/80287 status word and other condi- 
tions detected by the 8087/80287 exception handler, such as floating-point stack 
overflow and underflow. 


The bits in the value returned indicate the floating-point status. See the FLOAT.H 
include file for a complete definition of the bits returned by _ clear87. 


Many of the math library functions modify the 8087/80287 status word, with un- 
predictable results. Return values from _clear87 and _status87 become more reli- 
able as fewer floating-point operations are performed between known states of the 
floating-point status word. 


Standards: None 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 


_ control87, _ status87 


Example /* CLEAR87.C: This program creates various floating-point problems, 
* then uses _clear8/7 to report on these problems. 
* Compile this program with Optimizations disabled (/0d). Otherwise 
* the optimizer will remove the code associated with the unused 
* floating-point values. 


* / 


d#Finclude <stdio.h> 
dAinclude <float.h> 


Output 


_clear87 


void main( void ) 


{ 


double a = 1e-4@, b; 
float x, y; 


printf( "Status: %.4x - clear\n", _clear8/7() ); 


/* Store into y is inexact and underflows: */ 
yeas 
printf( "Status: %.4x - inexact, underflow\n", _clear87() ); 


/* y is denormal: */ 
b= y; 
printf( "Status: %.4x - denormal\n", _clear87() ); 


Status: Q@@0@ - clear 
Status: @@30 - inexact, underflow 
Status: @@02 - denorma| 
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clearerr 


Description Resets the error indicator for a stream. 
#include <stdio.h> 
void clearerr( FILE *stream ); 


stream Pointer to FILE structure 


Remarks The clearerr function resets the error indicator and end-of-file indicator for 
stream. Etror indicators are not automatically cleared; once the error indicator for 
a specified stream is set, operations on that stream continue to return an error 
value until clearerr, fseek, fsetpos, or rewind is called. 


Return Value None. 

Compatibility Standards: ANSI, UNIX 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 

See Also _eof, feof, ferror, perror 


Example /* CLEARERR.C: This program creates an error on the standard input 
* Stream, then clears it so that future reads won't fail. 
*« / 


d#Hinclude <stdio.h> 


void main( void ) 
{ 


int c; 


/* Create an error by writing to standard input. */ 
putc( ‘'c', stdin ); 
if( ferror( stdin ) ) 
{ 
perror( "Write error" ); 
clearerr( stdin ); 
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/* See if read causes an error. */ 
printf( "Will input cause an error? " ); 
c = getc( stdin ); 

if( ferror( stdin ) ) 


{ 
perror( "Read error" ); 
clearerr( stdin ); 
i 
} 
Output Write error: Error Q 


Will input cause an error? n 
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Description 


Remarks 


Return Value 


Compatibility 


See Also 


Example 


_ clearscreen 


Clears the specified area of the screen. 
#include <graph.h> 
void __ far _clearscreen( short area ); 


area Target area 


The _ clearscreen function erases the target area, filling it with the current back- 
ground color. The area argument can be one of the following manifest constants 
(defined in GRAPH.H): 


Constant Action 

_GCLEARSCREEN Clears and fills the entire screen 

_GVIEWPORT Clears and fills only within the current view port 
_GWINDOW Clears and fills only within the current text window 
None. 


Standards: None 
16-Bit: DOS 
32-Bit: None 


_getbkcolor, _setbkcolor 


/* CLRSCRN.C */ 


#tinclude <conio.h> 
#include <graph.h> 
#Hinclude <stdlib.h> 


_clearscreen 


void main( void ) 


{ 


Short xhalf, yhalf, xquar, yquar; 
Struct _videoconfig vc; 


/* Find a valid graphics mode. */ 
if( ! setvideomode( _MAXRESMODE ) ) 
exit( 1 ); 


_getvideoconfig( &vc ); 


xhalf = vc.numxpixels / 2; 
yhalf = vc.numypixels / 2; 
xquar = xhalf / 2; 
yquar = yhalf / 2; 


_setviewport( @, @, xhalf - 1, yhalf - 1 ); 
_rectangle( _GBORDER, @, @, xhalf - 1, yhalf - 1 ); 
_ellipse( _GFILLINTERIOR, xquar / 4, yquar / 4, 
xhalf - (xquar / 4), yhalf - (yquar / 4) ); 
_getch(); 
_clearscreen( _GVIEWPORT ); 


_getch(); 
_setvideomode( _DEFAULTMODE ); 
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Description 


Remarks 


Return Value 


Compatibility 


See Also 


clock 


Calculates the time used by the calling process. 
#include <time.h> 


clock_t clock( void ); 


The clock function tells how much processor time has been used by the calling 
process. The time in seconds is approximated by dividing the clock return value 
by the value of the CLOCKS_PER_SEC constant. 


In other words, the clock function returns the number of processor timer ticks that 
have elapsed. A timer tick is approximately equal to 1/CLOCKS_PER_ SEC 
seconds. 


In versions of Microsoft C prior to version 6.0, the CLOCKS_ prs SEC 
constant was called CLK_TCK. 


The clock function returns the product of the time in seconds and the value of the 
CLOCKS_PER_SEC constant. If the processor time is not available, the func- 
tion returns the value —1, cast as clock_t. 


In DOS, clock returns the time elapsed since the process started. This may not be 
equal to the actual processor time used by the process. 


Standards: ANSI 
16-Bit: DOS, QWIN, WIN 
32-Bit: DOS32X 


difftime, time 


Example 


Output 


clock 


/* CLOCK.C: This example prompts for how long the program is to run and 
* then continuously displays the elapsed time for that period. 
* / 


4Finclude <stdio.h> 
4tinclude <stdlib.h> 
deinclude <time.h> 


void sleep( clock_t wait ); 


void main( void ) 


{ 
long 1 = 600000L; 
clock_t start, finish; 
double duration; 
/* Delay for a specified time. */ 
printf( "Delay for three seconds\n" ); 
Sleep( (clock_t)3 * CLOCKS _PER_SEC ); 
printf( "Done!\n" ); 
/* Measure the duration of an event. */ 
printf( “Time to do %ld empty loops is ", i ); 
start = clock(); 
while( i-- ) 
finish = clock(); 
duration = (double)( finish - start) / CLOCKS PER_SEC; 
printf( "%2.1f seconds\n", duration ); 
i; 


/* Pauses for a specified number of microseconds. */ 
void sleep( clock_t wait ) 


{ 
clock_t goal; 
goal = wait + clock(); 
while( goal > clock() ) 
i; 


Delay for three seconds 
Done! 
Time to do 600000 empty loops is 2.@ seconds 
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Description 


Remarks 


Return Value 


Compatibility 


See Also 


_ close 


Closes a file. 


#include <io.h> Required only for function declarations 


#include <errno.h> 
int _ close( int handle ); 


handle Handle referring to open file 


The _ close function closes the file associated with handle. 


The _ close function returns 0 if the file was successfully closed. A return value of 
—] indicates an error, and errno is set to EBADF, indicating an invalid file-handle 
argument. 


Standards: UNIX 
16-Bit:. © DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 


Use _ close for compatibility with ANSI naming conventions of non-ANSI func- 
tions. Use close and link with OLDNAMES.LIB for UNIX compatibility. 


_chsize, _ creat, _dup, _dup2, _ open, — unlink 


Example /* OPEN.C: This program uses _open to open a file named OPEN.C for input 
* and a file named OPEN.OUT for output. The files are then closed. 


* / 


dtinclude <fcntl.h> 
#Hinclude <sys\types.h> 
d#Finclude <sys\stat.h> 
d#Finclude <io.h> | 
d#Finclude <stdio.h> 
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void main( void ) 


{ 

int FHL, the: 

fhl = _open( “OPEN.C", _O_RDONLY ); 

if( fhl == -1 ) 
perror( "open failed on input file" ); 

else 

{ 
printf( “open succeeded on input file\n" ); 
_close( fhl ); 

J 

fh2 = _open( “OPEN.OUT", _O WRONLY | _O_CREAT, _S_IREAD | _S_IWRITE ); 

WC fhe ==. -l. ) 
perror( "open failed on output file” ); 

else 

{ 
printf( "open succeeded on output file\n" ); 
sehkoset. “th2 Js 

} 

} 
Output open succeeded on input file 


open succeeded on output file 
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— commit 


Description Flushes a file directly to disk. 


#include <io.h> Required only for function declarations 


#include <errno.h> 
int _commit( int handle ); 


handle Handle referring to open file 


Remarks The _ commit function forces the operating system to write the file associated 
with handle to disk. This call ensures that the specified file is flushed immedi- 
ately—not at the operating system’s discretion. 


Return Value The _ commit function returns 0 if the file was successfully flushed to disk. A 
return value of —1 indicates an error, and errno is set to EBADF, indicating an in- 
valid file-handle argument. 


Compatibility Standards: None 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 

See Also _creat, _ open, _ read, _ write 


Example /* COMMIT.C illustrates low-level file I/O functions including: 
_close commit memset _open _write 


This is example code, to keep the code simple and readable 
return values are not checked. 


#Hinclude <io.h> 
d#Ainclude <stdio.h> 
deinclude <fcntl.h> 
d#tdefine MAXBUF 32 


int log_receivable( int ); 


—_ commit 


void main( void ) 


{ 
int fhandle; 
fhandle = _open( "TRANSACT.LOG", _O_APPEND | _0_CREAT | 
_O_ BINARY | _O_RDWR ); 
log_receivable( fhandle ); 
_close( fhandle ); 
} 


int log_receivable( int fhandile ) 

{ 

/* The log_receivable function prompts for a name and a monetary amount 
* and places both values into a buffer (buf). The _write function 

* writes the values to the operating system and the _commit function 

* ensures that they are written to a disk file. 

* / 


int 1; 
char buf [MAXBUF]; 


memset( buf, '\@', MAXBUF ); 
/* Begin Transaction. */ 


printf( “Enter name: " ); 
gets( buf ); 
FORK. 1s be DUP Pi es NOs: age) 


/* Write the value as a '\@' terminated string. */ 
_write( fhandle, buf, i+1 ); 
prIneTre “Ane ) 3 


memset( buf, '\@', MAXBUF ); 

printf( "Enter amount: $" ); 

gets( buf ); 

for( i = 1; buffLi] != '\@'; i++ ); 

/* Write the value as a ‘'\Q"' terminated string. */ 
_write( fhandle, buf, i+1 ); 

prince \n}s 


return _commit( fhandle ); 


/* The _commit function ensures that two important pieces of data are 


* Safely written to disk. The return value of the _commit function 
* 7s returned to the calling function. 
 / 
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_ control87 

Description Gets and sets the floating-point control word. 
#include <float.h> 


unsigned int _ control87( unsigned int new, unsigned int mask ); 


new New control-word bit values 
mask Mask for new control-word bits to set 
Remarks The _ control87 function gets and sets the floating-point control word. The float- 


ing-point control word allows the program to change the precision, rounding, and 
infinity modes in the floating-point-math package. Floating-point exceptions can 
also be masked or unmasked using the _ control87 function. 


If the value for mask is equal to 0, then _ control87 gets the floating-point control 
word. If mask is nonzero, then a new value for the control word is set in the follow- 
ing manner: for any bit that 1s on (equal to 1) in mask, the corresponding bit in new 
is used to update the control word. To put it another way, | 


fpcntrl = ((fpcntrl & ~mask) | (new & mask)) 
where fpcntr1 is the floating-point control word. 


The possible values for the mask constant (mask) and new control values (new) are 
shown in Table R.1. 


Table R.1 Hex Values 


Mask Hex Value Constant Hex Value 
MCW_EM Ox003F 
(Interrupt 
exception) 
_EM_INVALID 0x0001 


_EM_DENORMAL O0x0002 
_EM_ZERODIVIDE 0x0004 
_EM_ OVERFLOW 0x0008 
_EM_UNDERFLOW 0x0010 
_EM_INEXACT 0x0020 
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Table R.1 Hex Values (continued) 


Mask Hex Value Constant Hex Value 
MCW_IC Ox 1000 
(Infinity 
control) 
_IC_AFFINE Ox 1000 


_IC_PROJECTIVE Ox0000 


MCW_RC Ox0COO0 

(Rounding 

control) 
RC_CHOP Ox0COO0 
RC_UP Ox0800 
_RC_DOWN 0x0400 
_~RC_NEAR Ox0000 

MCW_PC 0x0300 

(Precision 

control) 
_PC_24 (24 bits) 0x0000 
_PC_53 (53 bits) Ox0200 
_PC_ 64 (64 bits) 0x0300 

Return Value The bits in the value returned indicate the floating-point control state. See the 


FLOAT.H include file for a complete definition of the bits returned by _ control87. 


Compatibility Standards: None 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 


See Also _clear87, _status87 
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Example /* CNTRL87.C: This program uses _control87 to output the control word, 
: * Set the precision to 24 bits, and reset the status to the default. 
* / 


d4Finclude <stdio.h> 
d4Ainclude <float.h> 


void main( void ) 
{ 
double a = Q.1; 


/* Show original control word and do calculation. */ 
printf( "Original: @x%.4x\n", _control87( 0, @) ); 
printf( "%1.1f * 41.1f = %.15e\n", a, a, a * a ); 


/* Set precision to 24 bits and recalculate. */ 
printf( "24-bit: Qx%.4x\n", _control87( _PC_24, MCW_PC ) ); 
printf( "41.1f * “21.1f = %.15e\n", a, a, a*a ); 


/* Restore to default and recalculate. */ 
printf( "Default: Q@x%.4x\n", _control87( CW_DEFAULT, Oxffff ) ); 
printf( "%1.1f * 41.1f = %.15e\n", a, a, a * a ); 


Output Original: 0x1332 
@.1 * 0.1 = 1.000000000000000c-002 
24-bit:  x1332 
Q@.1 * 0.1 = 9.999999776482582e-003 
Default: @x1032 
Q@.1 * 0.1 = 1.000000000000000c-002 


Description 


Remarks 


Return Value 


Compatibility 
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cos Functions 


Calculate the cosine (cos and _cosl) or hyperbolic cosine (cosh and _coshl). 
#include <math.h> 


double cos( double x ); 
double cosh( double «x ); 
long double _ cosl( long double x ); 


long double _ coshl( long double x ); 


x Angle in radians 


The cos and cosh functions return the cosine and hyperbolic cosine, respectively, 
of x. 


The _cosl and _coshl functions are the 80-bit counterparts and use the 80-bit, 10- 
byte coprocessor form of arguments and return values. See the reference page on 
the long double functions for more details on this data type. 


If x is large, a partial loss of significance in the result may occur in a call to cos, in 
which case the function generates a__PLOSS error. If x 1s so large that signifi- 
cance is completely lost, cos prints a_TLOSS message to stderr and returns 0. In 
both cases, errno is set to EKRANGE. 


If the result is too large in a cosh call, the function returns HUGE_ VAL and sets 
errno to ERANGE. This behavior can be changed with _matherr. 


cos, cosh 
Standards: ANSI, UNIX 
16-Bit: DOS, QWIN, WIN, WIN DLL 


32-Bit: DOS32X 
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_cosl, _ coshl 


Standards: None 


16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: None 

See Also acos functions, asin functions, atan functions, _matherr, sin functions, tan 
functions 


Example /* SINCOS.C: This program displays the sine, hyperbolic sine, cosine, 
* and hyperbolic cosine of pi / 2. 
* / 


dAinclude <math.h> 
dinclude <stdio.h> 


void main( void ) 


{ 
double pi = 3.1415926535; 
double x, y; 
xX = pi / 2; 
y = sin( x ): 
printf( "sin€ 4f ) = “f\n", x, y );3 
y = sinh( x ); 
printte “sinht -2F > = ZEN" xy ¥ Os 
y = cos( x ); 
printf( "cos( “2f ) = “f\n", x, y );3 
y = cosh( x ); 
printf( "cosh( 4f ) = &f\n",x, y ); 
} 
Output sin( 1.570796 ) = 1.000000 


sinh( 1.570796 ) = 2.301299 
cos( 1.570796 ) = 0.000000 
cosh( 1.570796 ) = 2.509178 


Description 


Remarks 


Return Value 


Compatibility 


See Also 
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_ cprintt 


Formats and prints to the console. 
#include <conio.h> Required only for function declarations 
int _cprintf( char *format [[, argument] ... ); 


format Format control string 


argument Optional arguments 


The _cprintf function formats and prints a series of characters and values directly 
to the console, using the _ putch function to output characters. Each argument (if 
any) is converted and output according to the corresponding format specification 
in format. The format has the same form and function as the format argument for 
the printf function; see printf for a description of the format and arguments. 


Note that unlike the fprintf, printf, and sprintf functions, _ cprintf does not trans- 
late line-feed characters into carriage-return—line-feed (CR-LF) combinations on 
output. 


The _ cprintf function returns the number of characters printed. 


Standards: None 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 


_cscanf, fprintf, printf, sprintf, vprintf 
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Example /* CPRINTF.C: This program displays some variables to the console. */ 
d#Hinclude <conio.h> 


void main( void ) 


{ 
int i= -16; h = 29; 
unsigned u = 62511; 
char Ca TA 
char SL] = "Test"; 
/* Note that console output does not translate \n as 
* Standard output does. Use \r\n instead. 
* / 
_cprintf( "%d %.4x %u %c &4s\r\n", i, h, u, c, s ); 
} 


Output -16 @@1d 62511 A Test 


Description 


Remarks 


Return Value 


Compatibility 


See Also 


Example 
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_ cputs 
Puts a string to the console. 
#include <conio.h> Required only for function declarations 
int _cputs( char *string ); 


string Output string 


The _cputs function writes the null-terminated string pointed to by string directly 
to the console. Note that a carriage-return—line-feed (CR-LF) combination is not 
automatically appended to the string. 


If successful, _ cputs returns a 0. If the function fails, it returns a nonzero value. 


Standards: None 


16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 
_ putch 


/* CPUTS.C: This program first displays a string to the console. */ 


#Ainclude <conio.h> 


Output 


void main( void ) 


/* String to print at console. Note the \r (return) character. */ 
char *buffer = "Hello world (courtesy of _cputs)!\r\n"; 


_cputs( buffer ); 


Hello world (courtesy of _cputs)! 
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Description 


Remarks 


_ creat 


Creates a new file. 


#include <sys\types.h> 
#include <sys\stat.h> 
#include <errno.h> 


#include <io.h> Required only for function declarations 
int _creat( char *filename, int pmode ); 


filename Path name of new file 


pmode Permission setting 


The _ creat function either creates a new file or opens and truncates an existing 
file. If the file specified by filename does not exist, a new file is created with the 
given permission setting and is opened for writing. If the file already exists and its 
permission setting allows writing, _creat truncates the file to length 0, destroying 
the previous contents, and opens it for writing. 


The permission setting, pmode, applies to newly created files only. The new file re- 
ceives the specified permission setting after it is closed for the first time. The 
integer expression pmode contains one or both of the manifest constants 
_S_ITWRITE and _S_IREAD, defined in SYS\STAT.H. When both of the con- 
stants are given, they are joined with the bitwise-OR operator (|). The pmode ar- 
gument is set to one of the following values: 


Value Meaning 

_S_IWRITE Writing permitted 
_S_IREAD Reading permitted 
_S_IREAD |_S_IWRITE Reading and writing permitted 


If write permission is not given, the file is read-only. Note that all files are always 
readable; it is not possible to give write-only permission. Thus, the modes 
_S_IWRITE and _S_TREAD | _S_TWRITE are equivalent. With DOS ver- 
sions 3.0 and later, files opened using _ creat are always opened in compatibility 
mode (see _sopen). With DOS32X, the files are always opened with 
_SH_DENYNO. 


Return Value 
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The _ creat function applies the current file-permission mask to pmode before 
setting the permissions (see _ umask). 


Note that the _ creat routine is provided primarily for compatibility with previous 
libraries. A call to_open with _O_ CREAT and _O_TRUNC in the oflag argu- 
ment is equivalent to _creat and is preferable for new code. 


If successful, _ creat returns a handle for the created file. Otherwise, it returns —1 
and sets errno to one of the following constants: 


Value Meaning 
EACCES Path name specifies an existing read-only file or specifies a 
directory instead of a file 
EMFILE No more handles available (too many open files) 
ENOENT Path name not found 
Compatibility Standards: UNIX 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 


See Also 


Example 


Use _ creat for compatibility with ANSI naming conventions of non-ANSI func- 
tions. Use creat and link with OLDNAMES.LIB for UNIX compatibility. 


_chmod, _ chsize, _ close, _dup, _dup2, _ open, _ sopen, _ umask 


/* CREAT.C: This program uses _creat to create the file (or truncate the 
* existing file) named data and open it for writing. 
* / 


#Hinclude <sys\types.h> 
#Finclude <sys\stat.h> 
#Hinclude <io.h> 
d#Finclude <stdio.h> 
#Hinclude <stdlib.h> 
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void main( void ) 


{ 
int fh; 
fh = _creat( "data", _S_IREAD | _S_IWRITE ); 
if( fh == -1 ) 
perror( "Couldn't create data file" ); 
else 
{ 
printf( "Created data file.\n" ); 
_close( fh ); 
} 
} 


Output Created data file. 


Description 


Remarks 


Return Value 


Compatibility 


See Also 
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_ escanft 


Reads formatted data from the console. 
#include <conio.h> Required only for function declarations 
int _cscanf( char *format |, argument] ... )3 


format Format-control string 


argument Optional arguments 


The _ cscanf function reads data directly from the console into the locations given 
by argument. The _ getche function is used to read characters. Each optional argu- 
ment must be a pointer to a variable with a type that corresponds to a type speci- 
fier in format. The format controls the interpretation of the input fields and has the 
same form and function as the format argument for the scanf function; see scanf 
for a description of format. 


While _ cscanf normally echoes the input character, it will not do so if the last call 
was to _ungetch. 


The _ cscanf function returns the number of fields that were successfully con- 
verted and assigned. The return value does not include fields that were read but 
not assigned. 


The return value is EOF for an attempt to read at end-of-file. This may occur 
when keyboard input is redirected at the operating system command-line level. A 
return value of 0 means that no fields were assigned. 


Standards: None 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 


_cprintf, fscanf, scanf, sscanf 
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Example 


Output 


_cscanf 


/* CSCANF.C: This program prompts for a string and uses _cscanf to read 
* in the response. Then _cscanf returns the number of items matched, 

* and the program displays that number. 

* / 


dFinclude <stdio.h> 
d#include <conio.h> 


void main( void ) 


{ 
int results, 10373 
_cprintf( "Enter three integers: "); 
result = _cscanf( "%i %i %i", &if@], &i[fl], &i[2] ); 
_cprintf( "\r\nYou entered " ); 
while( result-- ) 
_cprintf( "%i ", iLresult] ); 
Leprintre “\rAn™ 3 
I 


Enter three integers: 34 43 987k 
You entered 987 43 34 
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ctime 


Description Converts a time stored as a time_t value to a character string. 
#include <time.h> Required only for function declarations 
char *ctime( const time_t *timer ); 


timer Pointer to stored time 


Remarks The ctime function converts a time stored as a time_t value to a character string. 
The timer value is usually obtained from a call to time, which returns the number 
of seconds elapsed since midnight (00:00:00), December 31, 1899, Universal 
Coordinated Time. 


The string result produced by ctime contains exactly 26 characters and has the 
form of the following example: 


Wed Jan @2 02:03:55 1980\n\@ 


A 24-hour clock is used. All fields have a constant width. The newline character 
(\n) and the null character (’\0’) occupy the last two positions of the string. 


Calls to the ctime function modify the single statically allocated buffer used by the 
gmtime and the localtime functions. Each call to one of these routines destroys 
the result of the previous call. The ctime function also shares a static buffer with 
the asctime function. Thus, a call to ctime destroys the results of any previous call 
to asctime, localtime, or gmtime. 


Return Value The ctime function returns a pointer to the character string result. If time repre- 
sents a date before midnight, December 31, 1899, Universal Coordinated Time, 
ctime returns NULL. 


Compatibility Standards: ANSI, UNIX 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 


See Also asctime, _ ftime, gmtime, localtime, time 
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Example /* CTIME.C: This program gets the current time in time_t form, then uses 
* ctime to display the time in string form. 
* / 


d4Ainclude <time.h> 
dtinclude <stdio.h> 


void main( void ) 


{ 

time_t |time; 

time( &ltime ); 

printf( "The time is %s\n", ctime( &ltime ) ); 
} 


Output The time is Tue Jun 15 16:08:18 1999 
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_dieeetomsbin, dmsbintoieee 


Description Convert between IEEE double value and Microsoft (MS) binary double value. 
#include <math.h> 


int _dieeetomsbin( double *s7c8, double *dst8 ); 


int _dmsbintoieee( double *s7c3, double *dsté ); 


srcs Buffer containing value to convert 
dst8 Buffer to store converted value 
Remarks The _ dieeetomsbin routine converts a double-precision number in IEEE (Institute 


of Electrical and Electronic Engineers) format to Microsoft (MS) binary format. 
The routine _dmsbintoieee converts a double-precision number in MS binary for- 
mat to IEEE format. 


These routines allow C programs (which store floating-point numbers in the [IEEE 
format) to use numeric data in random-access data files created with those ver- 
sions of Microsoft Basic that store floating-point numbers in MS binary format, 
and vice versa. 


The argument src8 is a pointer to the double value to be converted. The result is 
stored at the location given by dsté. 


These routines do not handle IEEE NANs (“not a number’) and infinities. IEEE 
denormals are treated as O in the conversions. 


Return Value These functions return O if the conversion is successful and | if the conversion 
causes an overflow. 


Compatibility Standards: None 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: None 


See Also _ fieeetomsbin, _ fmsbintoieee 
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Description 


Remarks 


Return Value 


Compatibility 


See Also 


difftime 


Finds the difference between two times. 
#include <time.h> Required only for function declarations 
double difftime( time_t timer/, time_t timer ); 


timerO Beginning time 


timer Ending time 
The difftime function computes the difference between the supplied time values, 
timerO and timer]. 


The difftime function returns, in seconds, the elapsed time from timer0 to timer. 
The value returned is a double-precision number. 


Standards: ANSI, UNIX 


16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 
time 


Example /* DIFFTIME.C: This program calculates the amount of time needed to 
* do a floating-point multiply 50000 times. 


* / 


#Hinclude <stdio.h> 
dAinclude <stdlib.h> 
d#einclude <time.h> 


Output 
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void main( void ) 


{ 


time_t start, finish; 
unsigned loop; 
double result, elapsed_time; 


printf( "This program will do a floating point multiply 50000 times\n" ); 
printf( "Working...\n" ); 


time( &start ); 

for( loop = 0; loop < 500@0L; loop++ ) 
result = 3.63 * 5.27; 

time( &finish ); 


elapsed_time = difftime( finish, start ); 
printf( "\nProgram takes %6.2f seconds.\n", elapsed_time ); 


This program will do a floating point multiply 50000 times 
Working... 


Program takes 4.00 seconds. 
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_ disable 
Description Disables interrupts. 
#include <dos.h> 


void _ disable( void ); 


Remarks The _ disable routine disables interrupts by executing an 8086 CLI machine in- 
struction. Use _ disable before modifying an interrupt vector. 


Return Value None. 

Compatibility Standards: None 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: None 


See Also _ enable 


Description 


Remarks 


Return Value 


Compatibility 


See Also 


Example 


_ displaycursor 


_ displaycursor 


Sets the cursor toggle for graphics functions. 
#include <graph.h> 
short __ far _displaycursor( short flag ); 


flag Cursor state 


Upon entry into each graphic routine, the screen cursor is turned off. The 
_displaycursor function determines whether the cursor will be turned back on 
when programs exit graphic routines. If flag is set to _GCURSORON, the 
cursor will be restored on exit. If flag is set to _GCURSOROFYF, the cursor 
will be left off. 


The function returns the previous value of flag. There is no error return. 


Standards: None 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: None 


_ gettextcursor, _ settextcursor 


/* DISCURS.C: This program changes the cursor shape using _gettextcursor 
* and _settextcursor, and hides the cursor using _displaycursor. 


#Finclude <conio.h> 
#Hinclude <graph.h> 
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void main( void ) 
{ 
short oldcursor; 
short newcursor = 0x0Q7; /* Full block cursor */ 


/* Save old cursor shape and make sure cursor is on */ 
oldcursor = _gettextcursor(); 

_clearscreen( _GCLEARSCREEN ); 

_displaycursor( _GCURSORON ); 

_outtext( "\nOld cursor shape: " ); 

_getch(); 


/* Change cursor shape */ 

_outtext( "\nNew cursor shape: " ); 
_settextcursor( newcursor ); 
_getch(); 


/* Restore original cursor shape */ 
<OUGTEXLG "An 32 
_settextcursor( oldcursor ); 


Description 


Remarks 


Return Value 


Compatibility 


See Also 
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div 
Computes the quotient and the remainder of two integer values. 
#include <stdlib.h> 
div_t div( int numer, int denom ); 


numer Numerator 


denom Denominator 


The div function divides numer by denom, computing the quotient and the re- 
mainder. The div_t structure contains the following elements: 


Element Description 
int quot Quotient 
int rem Remainder 


The sign of the quotient is the same as that of the mathematical quotient. Its 
absolute value is the largest integer that is less than the absolute value of the 
mathematical quotient. If the denominator is 0, the program will terminate with 
an error message. 


The div function returns a structure of type div_t, comprising both the quotient 
and the remainder. The structure is defined in STDLIB.H. 


Standards: ANSI 


16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 
Idiv 
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Example 


Output 


div 


DIV.C: This example takes two integers as command-line arguments and 
displays the results of the integer division. This program accepts 
two arguments on the command line following the program name, then 
calls div to divide the first argument by the second. Finally, 

it prints the structure members quot and rem. 


d#FAinclude <stdlib.h> 
d#Hinclude <stdio.h> 
d#Finclude <math.h> 


void main( int argc, char *argv[] ) 


{ 


EG 


int x,y; 
div_t div_result; 


X 
8 


atoi( argv[l1] ); 
atoi( argv[2] ); 


printf( "x is 4d, y is %4d\n", x, y );3 

div_result = div( x, y ); 

printf( "The quotient is %d, and the remainder is 4d\n", 
div_result.quot, div_result.rem ); 


\LIBREF] div 876 13 


xX is 876, y is 13 
The quotient is 67, and the remainder is 5 


Description 


Remarks 


Return Value 


Compatibility 


See Also 
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—dos_allocmem 


Allocates a block of memory, using DOS service 0x48. 


#include <dos.h> 


#include <errno.h> 
unsigned _ dos_allocmem( unsigned size, unsigned “seg ); 


size Block size to allocate 


seg Return buffer for segment descriptor 


The _ dos_allocmem function uses DOS service 0x48 to allocate a block of 
memory size paragraphs long. (A paragraph is 16 bytes.) Allocated blocks are al- 
ways paragraph aligned. The segment descriptor for the initial segment of the new 
block is returned in the word that seg points to. If the request cannot be satisfied, 
the maximum possible size (in paragraphs) is returned in this word instead. 


If successful, the _dos_allocmem returns 0. Otherwise, it returns the DOS error 
code and sets errno to ENOMEM, indicating insufficient memory or invalid 
arena (memory area) headers. 


Standards: None 
16-Bit: DOS 
32-Bit: None 


_ alloca, calloc functions, _dos_freemem, _ dos_setblock, _halloc, malloc 
functions | 
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Example /* DALOCMEM.C: This program allocates 2@ paragraphs of memory, increases 
* the allocation to 4@ paragraphs, and then frees the memory space. 
* / 


d#Hinclude <dos.h> 
#FHinclude <stdio.h> 


void main( void ) 

{ 
unsigned segment; 
unsigned maxsize; 


/* Allocate 2@ paragraphs */ 

if( _dos_allocmem( 20, &segment ) != @ ) 
printf( "allocation failed\n" ); 

else 
printf( "allocation successful\n" ); 


/* Increase allocation to 4@ paragraphs */ 

if( _dos_setblock( 40, segment, &maxsize ) != @ ) 
printf( "allocation increase failed\n" ); 

else 
printf( "allocation increase successful\n" ); 


/* free memory */ 
if( _dos_freemem( segment ) != @ ) 
printf( "free memory failed\n" ); 
else 
printf( "free memory successful\n" ); 


Output allocation successful 
allocation increase successful 
free memory successful 


Description 


Remarks 


Return Value 


Compatibility 


See Also 


Example 
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_dos_ close 


Closes a file using system call Ox3E. 


#include <dos.h> 


#include <errno.h> 
unsigned _ dos_close( int handle ); 


handle Target file handle 


The _ dos_close function uses system call Ox3E to close the file indicated by 
handle. The file’s handle argument is returned by the call that created or last 
opened the file. 


The function returns 0 if successful. Otherwise, it returns the DOS error code and 
sets errno to EBADF, indicating an invalid file handle. 


Do not use the DOS interface I/O routines with the console, low-level, or stream 
I/O routines. | 


Standards: None 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: None 


_close, _creat, _dos_creat functions, _dos_open, _dos_read, _dos_ write, 
_dup, _open 


/* DOPEN.C: This program uses DOS I/0 functions to open and close a file. */ 


dAinclude <fcntl.h> 
dEinclude <stdio.h> 
d#Finclude <dos.h> 
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void main( void ) 
{ 
int fh; 


/* Open file with _dos_open function */ | 
if( _dos_open( "datal", _O_RDONLY, &fh ) != @ ) 
perror( "Open failed on input file\n" ); 

else 
printf( "Open succeeded on input file\n" ); 


/* Close file with _dos_close function */ 
if( _dos_close( fh ) != @ ) 
perror( "Close failed\n" ); 
else 
 printf( "File successfully closed\n" ); 
} 


Output Open succeeded on input file 
File successfully closed 
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_dos_ commit 


Description Flushes a file to disk using system call 0x68. 


#include <dos.h> 


#include <errno.h> 


unsigned _dos_commit( int handle ); 


handle Target file handle 


Remarks The _dos_commit function uses system call 0x68 to flush to disk the DOS 
buffers associated with the file indicated by handle. It also forces an update on the 
corresponding disk directory and the file allocation table. System call 0x68 en- 
sures that the specified file is flushed directly to disk and not flushed at the operat- 
ing system’s discretion. 


The system call used to implement _ dos_ commit is only available in DOS ver- 
sions 3.3 and later. Using _dos_ commit in earlier versions of DOS results in un- 
defined behavior. 


Do not use the DOS interface I/O routines with the console, low-level, or stream 
I/O routines. 


Return Value The function returns 0 if successful. Otherwise, it returns the DOS error code and 
sets errno to EBADF, indicating an invalid file handle. 


Compatibility Standards: None 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: None 
See Also _close, _creat, _dos_creat functions, _dos_open, _dos_read, _dos_write, 
_dup, _ open 
Example /* DCOMMIT.C illustrates DOS file I/0 functions including: 
* _dos_ commit _dos_creatnew _dos_write 
* _dos_creat _dos_close 


* / 
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dFinclude <dos.h> 
#Finclude <errno.h> 
d4Finclude <conio.h> 


void main( void ) 


{ 
char saveitL] = "Straight to disk. ", 
promptL] = "File exists, overwrite? [Ly|n] ", 
errL] = "Error occured. ", 
newline[L] = "\n\r"; 


int hfile, ch; 
unsigned count; 


/* Open file and create, overwriting if necessary. */ 
if( _dos_creatnew( "COMMIT.LOG", _A_NORMAL, &hfile ) != @ ) 


{ 
if( errno == EEXIST ) 
{ 
/* Use _dos_write to display prompts. Use bdos to call 
* function 1 to get and echo keystroke. 
* / 
_dos_write( 1, prompt, sizeof( prompt ) - 1, &count ); 
ch = bdos( 1, 0, @ ) & OxO0Off; 
if( (ch == 'y') |[[ (ch == 'Y') ) 
_dos_creat( "COMMIT.LOG", _A_NORMAL, &hfile ); 
_dos_write( 1, newline, sizeof( newline ) - 1, &count ); 
} 
} 


/* Write to file; output passes through operating system's buffers. 


if( _dos_write( hfile, saveit, sizeof( saveit ), &count ) != @ ) 
{ 

_dos_write( 1, err, sizeof( err ) - 1, &count ); 

_dos_write( 1, newline, sizeof( newline ) - 1, &count ); 
} 


/* Write directly to file with no intermediate buffering */ 
if( _dos_commit( hfile ) != @ ) 

{ 

_dos_write( 1, err, sizeof( err ) - 1, &count ); 
_dos_write( 1, newline, sizeof( newline ) - 1, &count ); 
} | 


/* Close file. */ 

if( _dos_close( hfile ) != @ ) 

{ 
_dos_write( 1, err, sizeof( err ) - 1, &count ); 
_dos_write( 1, newline, sizeof( newline ) - 1, &count ); 


* / 
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_dos_ creat Functions 


Description Create a new file. 


#include <dos.h> 


#include <errno.h> 


unsigned _ dos_creat( char *filename, unsigned attrib, int *handle ); 


unsigned _ dos_creatnew( char *filename, unsigned attrib, int *handle ); 


filename File path name 
attrib File attributes 
handle Handle return buffer 
Remarks The _ dos_creat and _ dos_creatnew routines create and open a new file named 


filename; this new file has the access attributes specified in the attrib argument. 
The new file’s handle is copied into the integer location pointed to by handle. The 
file is opened for both read and write access. If file sharing is installed, the file is 
opened in compatibility mode. 


The _ dos_creat routine uses system call 0x3C, and the _ dos_creatnew routine 
uses system call OxSB. If the file already exists, _dos_creat erases its contents 
and leaves its attributes unchanged; however, the _ dos_ creatnew routine fails if 
the file already exists. 


Return Value If successful, both routines return 0. Otherwise, they return the DOS error code 
and set errno to one of the following values: 
Constant Meaning 
EACCES Access denied because the directory is full or, for _dos_ creat 
only, the file exists and cannot be overwritten 
EEXIST File already exists (_dos_creatnew only) 
EMFILE Too many open file handles 


ENOENT Path or file not found 
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Compatibility Standards: None 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: None 


Example /* DCREAT.C: This program creates a file using the _dos_creat function. 
* program cannot create a new file using the _dos_creatnew function 
* because it already exists. 
* / 


d#Hinclude <stdio.h> 
d#Hinclude <stdlib.h> 
dAinclude <dos.h> 


void main( void ) 


{ 
int fhl, fh2; 
int result; 
if( _dos_creat( "data", _A_NORMAL, &fhl ) != @ ) 
printf( "Couldn't create data file\n" ); 
else 
{ 
printf( "Created data file.\n" ); 
/* If _dos_creat is successful, the _dos_creatnew cal] 
* will fail since the file exists 
* / 
if( _dos_creatnew( "data", _A_RDONLY, &fh2 ) != @ ) 
printf(. “Couldn't create data file\n™ ); 
else 
{ 
printf( "Created data file.\n" ); 
_dos_close( fh2 ); 
} 
_dos_close( fhl ); 
i: 
} 
Output Created data file. 


Couldn't create data file 


Description 


Remarks 
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_dos_ find Functions 


Find the file with the specified attributes or find the next file with the specified 
attributes. 


#include <dos.h> 


#include <errno.h> 


unsigned _ dos_findfirst( char *filename, unsigned attrib, 
struct _ find_t *fileinfo ); 


unsigned _ dos_findnext( struct _find_t *fileinfo ); 


filename Target filename 
attrib Target attributes 
fileinfo File-information buffer 


The _ dos_findfirst routine uses system call Ox4E to return information about the 
first instance of a file whose name and attributes match filename and attrib. 


The filename argument may use wildcards (* and ?). The attrib argument can be 
any of the following manifest constants: 


Constant Meaning 

_A_ARCH Archive. Set whenever the file is changed, and cleared by 
the DOS BACKUP command. 

_A_ HIDDEN Hidden file. Cannot be found with the DOS DIR 


command. Returns information about normal files as 
well as about files with this attribute. 


_A_ NORMAL Normal. File can be read or written without restriction. 


_A_RDONLY Read-only. File cannot be opened for writing, and a file 
with the same name cannot be created. Returns 
information about normal files as well as about files with 
this attribute. 


_A_SUBDIR Subdirectory. Returns information about normal files as 
well as about files with this attribute. 
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Constant Meaning 


_A_SYSTEM | System file. Cannot be found with the DOS DIR 
command. Returns information about normal files as 
well as about files with this attribute. 

_A_VOLID Volume ID. Only one file can have this attribute, and it 
must be in the root directory. 


Multiple constants can be combined (with the OR operator), using the vertical-bar 
(|) character. 


If the attrib argument to either of these functions is_A_ RDONLY, 

_A_ HIDDEN, _A_ SYSTEM, or _A_ SUBDIR, the function also returns 
any normal attribute files that match the filename argument. That is, a normal 
file does not have a read-only, hidden, system, or directory attribute. 


Information is returned in a _find_t structure, defined in DOS.H. The _ find_t 
structure contains the following elements: 


Element Description 

char reserved[21]| Reserved for use by DOS 

char attrib Attribute byte for matched path 

unsigned wr_ time Time of last write to file 

unsigned wr_ date Date of last write to file 

long size Length of file in bytes 

char name[13] Null-terminated name of matched file/directory, without 
the path 


The formats for the wr_time and wr_ date elements are in DOS format and are 
not usable by any other C run-time function. The time format is shown below: 


Bits Contents 

0-4 Number of 2-second increments (0-29) 
5-10 Minutes (0-59) 

11-15 Hours (Q— 23) 


The date format 1s shown below: 


Bits Contents 
0-4 Day of month (1-31) 
5-8 Month (1-12) 


9-15 Year (relative to 1980) 


Return Value 
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Do not alter the contents of the buffer between a call to _dos_findfirst and a sub- 
sequent call to the _ dos_findnext function. Also, the buffer should not be altered 
between calls to _ dos_findnext. 


The _ dos_findnext routine uses system call Ox4F to find the next name, if any, 
that matches the filename and attrib arguments specified in a prior call to 
_dos_findfirst. The fileinfo argument must point to a structure initialized by a pre- 
vious call to _dos_findfirst. The contents of the structure will be altered as de- 
scribed above if a match is found. 


If successful, both functions return 0. Otherwise, they return the DOS error code 
and set errno to ENOENT, indicating that filename could not be matched. 


Compatibility Standards: None 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: None 
Example /* DFIND.C: This program finds and prints all files in the current directory 


Output 


* with the .c extension. 
* / 


fHinclude <stdio.h> 
#Hinclude <dos.h> 


void main( void ) 


{ 

Struct _find_t c_file; 

/* find first .c file in current directory */ 

_dos_findfirst( "*.c", _A_NORMAL, &c_file ); 

printf( "Listing of .c files\n\n" ); 

printf( "File: %s is 4ld bytes\n", c_file.name, c_file.size ); 

/* find the rest of the .c files */ 

while( _dos_findnext( &c_file == 9) 

printf( "File: %s is 41d bytes\n", c_file.name, c_file.size ); 

} 


Listing of .c files 


File: CHDIR.C is 524 bytes 
File: SIGFP.C is 2674 bytes 
File: MAX.C is 258 bytes 
File: CGETS.C is 577 bytes 
File: FWRITE.C is 1123 bytes 
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Description 


Remarks 


Return Value 


Compatibility 


See Also 


Example 


_dos_freemem 


Releases a block of memory (0x49). 


#include <dos.h> 


#include <errno.h> 
unsigned _ dos_freemem( unsigned seg ); 


seg Block to be released 


The _ dos_freemem function uses system call 0x49 to release a block of memory 
previously allocated by _dos_allocmem. The seg argument is a value returned by 
a previous call to _dos_allocmem. The freed memory may no longer be used by 
the application program. 


If successful, _dos_freemem returns 0. Otherwise, it returns the DOS error code 
and sets errno to ENOMEM, indicating a bad segment value (one that does not 
correspond to a segment returned by a previous _dos_allocmem call) or invalid 
arena headers. 


Standards: None 
16-Bit: DOS 
32-Bit: None 


_dos_allocmem, _dos_setblock, free functions 


/* DALOCMEM.C: This program allocates 2@ paragraphs of memory, increases 
* the allocation to 4@ paragraphs, and then frees the memory space. 


d#Einclude <dos.h> 
dAinclude <stdio.h> 


Output 


void main( void ) 

{ 
unsigned segment; 
unsigned maxsize; 


/* Allocate 20 paragraphs */ 

if( _dos_allocmem( 20, &segment ) != @ ) 
printf( “allocation failed\n" ); 

else 
printf( "allocation successful\n" ); 


/* Increase allocation to 4@ paragraphs */ 
if( _dos_setblock( 40, segment, &maxsize ) 

printf( “allocation increase failed\n" 
else 


printf( "allocation increase successful\n" ); 


/* Free memory */ 
if( _dos_freemem( segment ) != @ ) 
printf( "free memory failed\n" ); 
else 
printf( "free memory successful\n" ); 


allocation successful 
allocation increase successful 
free memory successful 
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196 _dos_getdate 


Description 


Remarks 


Return Value 


Compatibility 


See Also 


_dos_ getdate 


Gets current system date using system call Ox2A. 
#include <dos.h> 
void _dos_getdate( struct _dosdate_t *date ); 


date Current system date 


The _ dos_ getdate routine uses system call 0x2A to obtain the current system 
date. The date is returned in a _dosdate_t structure, defined in DOS.H. 


The _ dosdate_t structure contains the following elements: 


Element Description 
unsigned char day 1-31 

unsigned char month 1-12 

unsigned int year 1980-2099 
unsigned char dayofweek 0-6 (0 = Sunday) 
None. 


Standards: None 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: None 


_dos_gettime, _dos_setdate, _dos_settime, gmtime, localtime, mktime, 
_strdate, _strtime, time 
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Example /* DGTIME.C: This program gets and displays current date and time values. */ 


dAinclude <stdio.h> 
4Finclude <dos.h> 


void main( void ) 


{ 
struct _dosdate_t date; 
struct _dostime_t time; 


/* Get current date and time values */ 


_dos_getdate( &date ); 
_dos_gettime( &time ); 


printf( "Today's date is %4d-%d-%d\n", date.month, date.day, date.year ); 
printf( "The time is %402d:%02d\n", time.hour, time.minute ); 


Output Today's date is 12-15-1999 
The time is 18:07 


198  _dos_getdiskfree 


Description 


Remarks 


Return Value 


Compatibility 


See Also 


_dos_getdiskfree 


Gets disk information using system call 0x36. 


#include <dos.h> 


#include <errno.h> 
unsigned _ dos_getdiskfree( unsigned drive, struct _ diskfree_t “diskspace ); 


drive Drive number (default is 0) 


diskspace Buffer to hold disk information 


The _ dos_getdiskfree routine uses system call 0x36 to obtain information on the 
disk drive specified by drive. The default drive is 0, drive A is 1, drive B is 2, and 
so on. Information is returned in the _ diskfree_t structure (defined in DOS.H) 
pointed to by diskspace. 


The struct _diskfree_t structure contains the following elements: 


Element Description 

unsigned total_clusters Total clusters on disk 
unsigned avail_clusters Available clusters on disk 
unsigned sectors_ per_ cluster Sectors per cluster 
unsigned bytes_per_sector Bytes per sector 


If successful, the function returns 0. Otherwise, it returns a nonzero value and sets 
errno to EINVAL, indicating that an invalid drive was specified. 


Standards: None 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: None 


_dos_getdrive, _ dos_setdrive 


Example 


Output 
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/* DGDISKFR.C: This program displays information about the default disk drive. 
* / 


d#Hinclude <stdio.h> 
d4Einclude <dos.h> 


void main( void ) 


{ 
Struct _diskfree_t drive; 
/* Get information on default disk drive Q */ 
_dos_getdiskfree( @, &drive ); 
printf( “total clusters: 4d\n", drive.total_clusters ); 
printf( “available clusters: 4d\n", drive.avail_clusters ); 
printf( “sectors per cluster: 4d\n", drive.sectors_per_cluster ); 
printf( “bytes per sector: %4d\n", drive.bytes_per_sector ); 
I 


total clusters: 99013 
available clusters: 6030 
sectors per cluster: 4 
bytes per sector: 512 


200 ##_dos_getdrive 
_dos_getdrive 

Description Gets the current disk drive using system call Ox19. 
#include <dos.h> 
void _ dos_ getdrive( unsigned *drive ); 


drive Current-drive return buffer 


Remarks The _ dos_ getdrive routine uses system call 0x19 to obtain the current disk 
drive. The current drive is returned in the word that drive points to: 1 = drive A, 
2 = drive B, and so on. 


Return Value None. 

Compatibility Standards: None 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: None 

See Also _dos_getdiskfree, _dos_setdrive, _ getdrive 


Example /* DGDRIVE.C: This program prints the letter of the current drive, 
* changes the default drive to A, then returns the number of disk drives. 
* / 


d#Hinclude <stdio.h> 
dEinclude <dos.h> 


void main( void ) 

{ 
unsigned olddrive, newdrive; 
unsigned number_of_drives; 


/* Print current default drive information */ 
_dos_getdrive( &olddrive ); 
printf( "The current drive is: %c\n", ‘'A' + olddrive - 1 ); 
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/* Set default drive to be drive A */ 
printf( "Changing default drive to A\n"); 
_dos_setdrive( 1, &number_of_drives ); 


/* Get new default drive information and total number of drives */ 
_dos_getdrive( &newdrive ); 

printf( "The current drive is: %c\n", ‘A' + newdrive - 1 ); 
printf( "Number of logical drives: %4d\n", number_of_drives ); 


/* Restore default drive */ 
_dos_setdrive( olddrive, &number_of_drives ); 


Output The current drive is: C 
Changing default drive to A 
The current drive is: A 
Number of logical drives: 26 
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_dos_ gettileattr 


Description Gets the current attributes of a file or directory, using system call 0x43. 


#include <dos.h> 


#include <errno.h> 


unsigned _ dos_ getfileattr( char *pathname, unsigned “attrib ); 


pathname Full path of target file/directory 
attrib Word to store attributes in 
Remarks The _ dos_ getfileattr routine uses system call 0x43 to obtain the current attributes 


of the file or directory pointed to by pathname. The attributes are copied to the 
low-order byte of the attrib word. Attributes are represented by manifest con- 
stants, as described below: 


Constant Meaning 

_A_ARCH Archive. Set whenever the file is changed, or cleared by the 
DOS BACKUP command. 

_A_ HIDDEN Hidden file. Cannot be found by a directory search. 

_A_NORMAL Normal. File can be read or written without restriction. 

_A_RDONLY Read-only. File cannot be opened for a write, and a file with the 
same name cannot be created. 

_A_ SUBDIR Subdirectory. 

_A_SYSTEM System file. Cannot be found by a directory search. 

_A_ VOLID Volume ID. Only one file can have this attribute, and it must be 


in the root directory. 


Return Value If successful, the function returns 0. Otherwise, it returns the DOS error code and 
sets errno to ENOENT, indicating that the target file or directory could not be 
found. 

Compatibility Standards: None 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: None 


See Also _access, _ chmod, _ dos_setfileattr, _ umask 
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Example /* DGFILEAT.C: This program creates a file with the specified attributes, 
* then prints this information before changing the file attributes back 
* to normal. 
* / 


dFinclude <stdio.h> 
d#Finclude <dos.h> 


void main( void ) 

{ 
unsigned oldattrib, newattrib; 
Tht: bh 


/* Get and display file attribute */ 
_dos_getfileattr( "DGFILEAT.C", &oldattrib ); 
printf( "Attribute: @x%.4x\n", oldattrib ); 
if( ( oldattrib & _A_RDONLY ) != @ ) 

printf( "Read only file\n" ); 
else 

printf( "Not a read only file.\n" ); 


/* Reset file attribute to normal file */ 
_dos_setfileattr( "DGFILEAT.C", _A_RDONLY ); 
_dos_getfileattr( "DGFILEAT.C", &newattrib ); 
printf( "Attribute: @x%.4x\n", newattrib ); 


/* Restore file attribute */ 
_dos_setfileattr( "DGFILEAT.C", oldattrib ); 
_dos_getfileattr( "DGFILEAT.C", &newattrib ); 
printf( "Attribute: @x%.4x\n", newattrib ); 


Output Attribute: 0x0020 
Not a read only file. 
Attribute: 0x0001 
Attribute: @x@020 


204 _dos_getftime 


Description 


Remarks 


Return Value 


Compatibility 


See Also 


_dos_getftime 


Gets the date and time a file was last written, using system call 0x57. 


#include <dos.h> 


#include <errno.h> 


unsigned _ dos_ getftime( int handle, unsigned “date, unsigned *time ); 


handle Target file 
date Date-return buffer 
time Time-return buffer 


The _dos_ getftime routine uses system call 0x57 to get the date and time that the 
specified file was last written. The file must have been opened with a call to 
_dos_open or _ dos_creat prior to calling _ dos_ getftime. The date and time are 
returned in the words pointed to by date and time. The values appear in the DOS 
date and time format: 


Time Bits Meaning 

0-4 Number of 2-second increments (0 —29) 
5-10 Minutes (0-59) 

11-15 Hours (0-23) 

Date Bits Meaning 

0-4 Day (1-31) 

5-8 Month (1-12) 

9-15 Year (1980 —2099) 


If successful, the function returns 0. Otherwise, it returns the DOS error code and 
sets errno to EBADF, indicating that an invalid file handle was passed. 


Standards: None 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: None 


_dos_setftime, _ fstat, _ stat 


Example 


_dos_getftime 


/* DGFTIME.C: This program displays and modifies the date and time 
* fields of a file. 
* / 


#Finclude <fcntl.h> 
d#Finclude <stdio.h> 
#Finclude <stdlib.h> 
#Hinclude <dos.h> 


void main( void ) 
{ 

/* FEDC BA98 7654 3210 * / 
unsigned new_date = O@x26cf; /* Q0010 0110 1100 1111 12/15/99 */ 
unsigned new_time = @x48eQ@; /* Q0100 1000 1110 0000 9:07 AM ¥*/ 
unsigned old_date, old_time; 


int fh; 


/* Open file with _dos_open function */ 
if( _dos_open( "dgftime.obj", _O RDONLY, &fh ) != @ ) 
exit( 1 ); 


/* Get file date and time */ 

_dos_getftime( fh, &old_date, &old_time ); 
printf( "Old date field: @x%.4x\n", old_date ); 
printf( "Old time field: @x%.4x\n", old_time ); 
system( "dir dgftime.obj" ); 


/* Modify file date and time */ 

if( !_dos_setftime( fh, new_date, new_time ) ) 

{ 
_dos_getftime( fh, &new_date, &new_time ); 
printf( "New date field: @x%.4x\n", new_date ); 
printf( "New time field: @x%.4x\n", new_time ); 
System( “dir dgftime.obj" ); 


/* Restore date and time */ 
_dos_setftime( fh, old_date, old_time ); 
} 
_dos_close( fh ); 
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Output Old date field: Qx274f 
Old time field: @x94bb 


Volume in drive C is ZEPPELIN 
Directory of C:\LIBREF 


DGFTIME OBJ 3925. “6715°99 6237p 
1 File(s) 13676544 bytes free 


New date field: Q@x26cf 
New time field: @x48e@ 


Volume in drive C is ZEPPELIN 
Directory of C:\LIBREF 


DGFTIME OBd 3923 12-15-99 9:07a 
1 File(s) 13676544 bytes free 
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_dos_gettime 
Description Gets the current system time, using system call 0x2C. 
#include <dos.h> 
void _dos_ gettime( struct _dostime_t *time ); 


time Current system time 


Remarks The _ dos_ gettime routine uses system call 0x2C to obtain the current system 
time. The time is returned in a __dostime_t structure, defined in DOS.H. 


The dostime_t structure contains the following elements: 


Element Description 
unsigned char hour 0-23 
unsigned char minute 0-59 
unsigned char second O-59 


unsigned char hsecond 1/100 second; 0-99 


Return Value None. 

Compatibility Standards: None 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: None 


See Also _dos_ getdate, _dos_setdate, _dos_settime, gmtime, localtime, _strtime 
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Example /* DGTIME.C: This program gets and displays current date and time values. */ 


d#Finclude <stdio.h> 
dEinclude <dos.h> 


void main( void ) 

{ 
struct _dosdate_t date; 
struct _dostime_t time; 


/* Get current date and time values */ 


_dos_getdate( &date ); 
_dos_gettime( &time ); 


printf( "Today's date is 4d-%d-%d\n", date.month, date.day, date.year ); 
printf( "The time is 202d:%02d\n", time.hour, time.minute ); 


Output Today's date is 12-15-1999 
The time is 18:07 
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_dos_getvect 


Description Gets the current value of the interrupt vector, using system call 0x35. 
#include <dos.h> 
void (__cdecl __interrupt __ far *_dos_getvect( unsigned intnum))( ); 


inthum Target interrupt vector 


Remarks The _ dos_ getvect routine uses system call 0x35 to get the current value of the in- 
terrupt vector specified by intnum. 


This routine is typically used in conjunction with the _dos_setvect function. To 
replace an interrupt vector, first save the current vector of the interrupt using 
_dos_getvect. Then set the vector to your own interrupt routine with 
_dos_setvect. The saved vector can later be restored, if necessary, using 
_dos_setvect. The user-defined routine may also need the original vector in order 
to call that vector or chain to it with _chain_ intr. 


Return Value The function returns a far pointer for the intnum interrupt to the current handler, if 
there is one. 


Compatibility Standards: None 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: None 


See Also _chain_intr, _dos_keep, _dos_setvect 
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Description 


Remarks 


_dos_keep 


Installs TSR (terminate-and-stay-resident) programs in memory, using system call 
Ox31. 


#include <dos.h> 


void _ dos_keep( unsigned retcode, unsigned memsize ); 


retcode Exit status code 
memsize Allocated resident memory (in 16-byte 
paragraphs) 


The _dos_ keep routine installs TSRs (terminate-and-stay-resident programs) in 
memory, using system call 0x31. 


The routine first exits the calling process, leaving it in memory. It then returns the 
low-order byte of retcode to the parent of the calling process. Before returning ex- 
ecution to the parent process, _dos_keep sets the allocated memory for the now- 
resident process to memsize 16-byte paragraphs. Any excess memory is returned 
to the system. 


The _ dos_ keep function calls the same internal routines called by exit. It there- 
fore takes the following actions: 


= Calls any functions that have been registered by atexit or _ onexit calls. 
= Flushes all file buffers. 


= Restores interrupt vectors replaced by the C startup code. The primary one is in- 
terrupt 0 (divide by zero). If the emulator math library is used and there is no co- 
processor, interrupts 0x34 through 0x3D are restored. If there is a coprocessor, 
interrupt 2 1s restored. 


Do not use the emulator math library in TSRs unless you are familiar with the 
startup code and the coprocessor. Use the alternate math package if the TSR must 
do floating-point math. 


Do not run programs that use _dos_keep from inside the Microsoft Programmer’ s 
WorkBench environment, since doing so causes subsequent memory problems. 
The _ dos_keep function terminates the program when executed in the 
Programmer’s WorkBench environment. 
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Return Value None. 

Compatibility Standards: None 
16-Bit: DOS 
32-Bit: None 


See Also _cexit, _chain_intr, _dos_getvect, _dos_setvect, _ exit 


212 _doS_open 


Description 


Remarks 


_dos_ open 


Opens a file, using system call Ox3D. 


#include <dos.h> 

#include <errno.h> 

#include <fentl.h> Access mode constants 
#include <share.h> Sharing mode constants 


unsigned _dos_open( char “filename, unsigned mode, int “handle ); 


filename Path to an existing file 
mode Permissions 
handle Pointer to integer 


The _dos_open routine uses system call Ox3D to open the existing file pointed to 
by filename. The handle for the opened file is copied into the integer pointed to by 
handle. The mode argument specifies the file’s access, sharing, and inheritance 
modes by combining (with the OR operator) manifest constants from the three 
groups shown below. At most, one access mode and one sharing mode can be 
specified at a time. 


Constant Mode Meaning 
_O_RDONLY Access Read-only 
_O_WRONLY Access Write-only 
_O_RDWR Access Both read and write 
_SH_COMPAT Sharing Compatibility 
_SH_DENYRW Sharing Deny reading and writing 
_SH_DENYWR Sharing Deny writing 
_SH_DENYRD Sharing Deny reading 
_SH_DENYNO Sharing Deny neither 
_O_NOINHERIT Inheritance by the child File is not inherited 
process 


Do not use the DOS interface I/O routines in conjunction with the console, low- 
level, or stream I/O routines. 


Return Value 
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If successful, the function returns 0. Otherwise, it returns the DOS error code and 
sets errno to one of the following manifest constants: 


Constant Meaning 

EACCES Access denied (possible reasons include specifying a directory 
or volume ID for filename, or opening a read-only file for write 
access) 

EINVAL Sharing mode specified when file sharing not installed, or access- 
mode value is invalid 

EMFILE Too many open file handles 

ENOENT Path or file not found 

Compatibility Standards: None 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: None 


See Also 


Example 


Output 


_dos_close, _dos_read, _dos_write 


/* DOPEN.C: This program uses DOS 1/0 functions to open and close a file. */ 


dAinclude <fcntl.h> 
4#FAinclude <stdio.h> 
d#FAinclude <dos.h> 


void main( void ) 


if( _dos_open( "datal", _O_RDONLY, &fh ) != @ ) 
perror( "Open failed on input file\n" ); 


printf( "Open succeeded on input file\n" ); 


printf( "File successfully closed\n" ); 


{ 
int fh; 
/* Open file with _dos_open function */ 
else 
/* Close file with _dos_close function */ 
if( _dos_ close( fh ) != @ ) 
perror( "Close failed\n" ); 
else 
} 


Open succeeded on input file 


File successfully closed 
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Description 


Remarks 


Return Value 


Compatibility 


See Also 


_dos_read 


Reads data from a file, using system call Ox3F. 
#include <dos.h> 


unsigned _ dos_read( int handle, void __ far *buffer, unsigned count, 
unsigned *“numread ); 


handle File to read 

buffer Buffer to write to 

count Number of bytes to read 
numread Number of bytes actually read 


The _ dos_read routine uses system call Ox3F to read count bytes of data from the 
file specified by handle. The routine then copies the data to the buffer pointed to 
by buffer. The integer pointed to by numread will show the number of bytes actu- 
ally read, which may be less than the number requested in count. If the number of 
bytes actually read is 0, it means the routine tried to read at end-of-file. 


Do not use the DOS interface I/O routines in conjunction with the console, low- 
level, or stream I/O routines. 


If successful, the function returns 0. Otherwise, it returns the DOS error code and 
sets errno to one of the following constants: 


Constant Meaning 
EACCES Access denied (handle is not open for read access) 
EBADF File handle is invalid 


Standards: None 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: None 


_dos_close, _dos_ open, —dos_ write, _ read 


Example 


Output 
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/* DREAD.C: This program uses the DOS I/0 operations to read the contents 


* of a file. 


#Hinclude <fcntl.h> 

dHinclude <stdlib.h> 
#Hinclude <stdio.h> 

#Hinclude <dos.h> 


void main( void ) 


i 


int fh; 
char buffer[5@]; 
unsigned number_read; 


/* Open file with _dos_open function */ 

if( _dos_open( "dread.c", _O_RDONLY, &fh ) != @ ) 
perror( “Open failed on input file\n" ); 

else 
printf( "Open succeeded on input file\n" ); 


/* Read data with _dos_read function */ 


_dos_read( fh, buffer, 50, &number_read ); 


printf( "First 4@ characters are: %.4@s\n\n", buffer ); 


/* Close file with _dos_close function */ 
_dos_close( fh ); 


Open succeeded on input file 
First 40 characters are: /* DREAD.C: This program uses the DOS I/ 


216 _dos_setblock 


Description 


Remarks 


Return Value 


Compatibility 


See Also 


Example 


_dos_ setblock 


Changes the size of a memory segment, using system call Ox4A. 
#include <dos.h> 


unsigned _ dos_setblock( unsigned size, unsigned seg, unsigned *maxsize ); 


size New segment size 
seg Target segment 
maxsize Maximum-size buffer 


The _ dos_setblock routine uses system call Ox4A to change the size of seg, pre- 
viously allocated by _dos_allocmem, to size paragraphs. If the request cannot be 
satisfied, the maximum possible segment size is copied to the buffer pointed to by 
maxsize. 


The function returns 0 if successful. If the call fails, it returns the DOS error code 
and sets errno to ENOMEM, indicating a bad segment value was passed. A bad 
segment value is one that does not correspond to a segment returned from a pre- 
vious _dos_allocmem call, or one that contains invalid arena headers. 


Standards: None 
16-Bit: DOS 
32-Bit: None 


_dos_allocmem, _ dos_freemem, realloc functions 


/* DALOCMEM.C: This program allocates 2@ paragraphs of memory, increases 
* the allocation to 4@ paragraphs, and then frees the memory space. 


d#Einclude <dos.h> 
d#Hinclude <stdio.h> 


Output 


_dos_ setblock 


void main( void ) 


{ 


unsigned segment; 
unsigned maxsize; 


/* Allocate 20 paragraphs */ 

if( _dos_allocmem( 20, &segment ) != @ ) 
printf( “allocation failed\n" ); 

else 
printf( “allocation successful\n" ); 


/* Increase allocation to 4@ paragraphs */ 

if( _dos_setblock( 40, segment, &maxsize ) != @ ) 
printf( "allocation increase failed\n" ); 

else 
printf( "allocation increase successful\n" ); 


/* Free memory */ 
if( _dos_freemem( segment ) != @ ) 
printf( "free memory failed\n" ); 
else 
printf( "free memory successful\n" ); 


allocation successful 
allocation increase successful 
free memory successful 
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_dos_setdate 

Description Sets the current system date, using system call Ox2B. 
#include <dos.h> 
unsigned _ dos_setdate( struct _dosdate_t *date ); 


date New system date 


Remarks The _ dos_setdate routine uses system call 0x2B to set the current system date. 
The date is stored in the _dosdate_t structure pointed to by date, defined in 
DOS.H. The _ dosdate_t structure contains the following elements: 


Element Description 
unsigned char day 1-31 
unsigned char month 1-12 
unsigned int year 1980 — 2099 
unsigned char dayofweek 0-6 (0 = Sunday) 
Return Value If successful, the function returns 0. Otherwise, it returns a nonzero value and sets 


errno to EINVAL, indicating an invalid date was specified. 


Compatibility Standards: None 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: None 
See Also _dos_ getdate, _ dos_ gettime, _ dos_settime, gmtime, localtime, mktime, 


_strdate, _strtime, time 
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Example /* DSTIME.C: This program changes the time and date values and displays the 
* new date and time values. 
* / 


4Hinclude <dos.h> 
#Hinclude <conio.h> 
fHinclude <stdio.h> 
#Hinclude <time.h> 


void main( void ) 

{ 
struct _dosdate_t olddate, newdate = { { 4 } 
struct _dostime_t oldtime, newtime ‘oe ec as 
char datebuf[40], timebufl40]; 
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/* Get current date and time values */ 

_dos_getdate( &olddate ); 

_dos_gettime( &oldtime ); 

printf( "%s mS\n" , _Sstrdate( datebuf ), _strtime( timebuf ) ); 


/* Modify date and time structures */ 

_dos_setdate( &newdate ); 

_dos_settime( &newtime ); 

printf( "%s “S\n" , _strdate( datebuf ), _strtime( timebuf ) ); 


/* Restore old date and time */ 
_dos_setdate( &olddate ); 
_dos_settime( &oldtime ); 


Output 12/15/99 18:26:09 
07/04/99 03:45:30 


220 _dos_setdrive 


Description 


Remarks 


Return Value 


Compatibility 


See Also 


Example 


_dos_setdrive 


Sets the default drive, using system call Ox0E. 
#include <dos.h> 
void _dos_setdrive( unsigned drive, unsigned *“numdrives ); 


drive New default drive 


numdrives | Total drives available 


The _ dos_setdrive routine uses system call OxOE to set the current default drive 
to the drive argument: | = drive A, 2 = drive B, and so on. The numdrives argu- 
ment indicates the total number of drives in the system. If this value is 4, for ex- 
ample, it does not mean the drives are designated A, B, C, and D; it means only 
that four drives are in the system. 


There is no return value. If an invalid drive number is passed, the function fails 
without indication. Use the _ dos_ getdrive routine to verify whether the desired 
drive has been set. 


Standards: None 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: None 


_dos_getdiskfree, _dos_getdrive 


/* DGDRIVE.C: This program prints the letter of the current drive, 
* changes the default drive to A, then returns the number of disk drives. 


d#Einclude <stdio.h> 
dHinclude <dos.h> 


Output 


_dos_setdrive 


void main( void ) 


{ 


unsigned olddrive, newdrive; 
unsigned number_of_drives; 


/* Print current default drive information */ 


_dos_getdrive( &olddrive ); 


printf( "The current drive is: %c\n", ‘'A' + olddrive - 1 ); 


/* Set default drive to be drive A */ 
printf( "Changing default drive to A\n"); 
_dos_setdrive( 1, &number_of_drives ); 


/* Get new default drive information and total number of drives */ 
_dos_getdrive( &newdrive ); 

printf( "The current drive is: %c\n", 'A' + newdrive - 1 ); 
printf( "Number of logical drives: 4d\n", number_of_drives ); 


/* Restore default drive */ 
_dos_setdrive( olddrive, &number_of_drives ); 


The current drive is: C 
Changing default drive to A 
The current drive is: A 
Number of logical drives: 26 
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Description 


Remarks 


Return Value 


_dos_settfileattr 


Sets the attributes of the file or directory, using system call 0x43. 
#include <dos.h> 
unsigned _ dos_setfileattr( char *pathname, unsigned attrib ); 


pathname Full path of target file/directory 


attrib New attributes 


The _dos_setfileattr routine uses system call 0x43 to set the attributes of the file 
or directory pointed to by pathname. The actual attributes are contained in the low- 
order byte of the attrib word. Attributes are represented by manifest constants, as 
described below: 


Constant Meaning 

_A_ARCH Archive. Set whenever the file is changed, or cleared by the 
DOS BACKUP command. | 

_A_ HIDDEN Hidden file. Cannot be found by a directory search. 

_A_ NORMAL Normal. File can be read or written to without restriction. 

_A_RDONLY Read-only. File cannot be opened for writing, and a file with the 
same name cannot be created. 

_A_SUBDIR Subdirectory. 

_A_SYSTEM System file. Cannot be found by a directory search. 

_A_VOLID Volume ID. Only one file can have this attribute, and it must be 


in the root directory. 
The function returns 0 if successful. Otherwise, it returns the DOS error code and 
sets errno to one of the following: 


Constant Meaning 


EACCES Access denied; cannot change the volume ID or the subdirectory. 
ENOENT No file or directory matching the target was found. 
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Compatibility Standards: None 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: None 

See Also _dos_ getfileattr 


Example /* DGFILEAT.C: This program creates a file with the specified attributes, 
* then prints this information before changing the file attributes back 
* to normal. 
* / 


dFinclude <stdio.h> 
dEinclude <dos.h> 


void main( void ) 

{ 
unsigned oldattrib, newattrib; 
int fh; 


/* Get and display file attribute */ 
_dos_getfileattr( "DGFILEAT.C", &oldattrib ); 
printf( "Attribute: @x%.4x\n", oldattrib ); 
if( ( oldattrib & _A_RDONLY ) != @ ) 

printf( “Read only file\n" ); 
else 

printf( "Not a read only file.\n" ); 


/* Reset file attribute to normal file */ 
_dos_ setfileattr( "DGFILEAT.C", A RDONLY ); 
_dos_getfileattr( "DGFILEAT.C", &newattrib ); 
printf ( "Attribute: @x%.4x\n", newattrib ); 


/* Restore file attribute */ 
_dos_setfileattr( "DGFILEAT.C", oldattrib ); 
_dos_getfileattr( "DGFILEAT.C", &newattrib ): 
printf( "Attribute: @x%.4x\n", newattrib ); 


Output Attribute: @x0020 
Not a read only file. 
Attribute: @x@Q001 
Attribute: @x@020 
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Description 


Remarks 


Return Value 


Compatibility 


_dos_setftime 


Sets the date and time for a file, using system call 0x57. 
#include <dos.h> 


unsigned _ dos_setftime( int handle, unsigned date, unsigned time ); 


handle Target file 
date Date of last write 
time Time of last write 


The _ dos_setftime routine uses system call 0x57 to set the date and time at which 
the file identified by handle was last written to. These values appear in the DOS 
date and time format, described in the following lists: 


Time Bits Meaning 

0 a Number of two-second increments (0 —29) 

5-10 Minutes (0-59) 

11-15 Hours (0-23) 

Date Bits Meaning 

0-4 Day (1-31) 

5-8 | Month (1-12) 

9-15 Year since 1980 (for example, 1999 is stored as 9) 


If successful, the function returns 0. Otherwise, it returns the DOS error code and 
sets errno to EBADF, indicating that an invalid file handle was passed. 


Standards: None 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: None 


See Also 


Example 
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_dos_ getftime, _ fstat, _ stat 


/* DGFTIME.C: This program displays and modifies the date and time 
* fields of a file. 
* / 


dFinclude <fcntl.h> 
dFinclude <stdio.h> 
4#Finclude <stdlib.h> 
4Hinclude <dos.h> 


void main( void ) 
{ 

/* FEDC BA98 7654 3210 a / 
unsigned new_date = Qx26cf; /* @@010 0110 1100 1111 12/15/99 */ 
unsigned new_time = Qx48eQ; /* 0100 1000 1110 0000 9:07 AM x/ 
unsigned old_date, old _time; 


int fh; 


/* Open file with _dos_open function */ 
if( _dos_open( "dgftime.obj", _O_RDONLY, &fh ) != @ ) 
exit( 1 ); 


/* Get file date and time */ 

_dos_getftime( fh, &old_date, &old_time ); 
printf( "Old date field: @x%.4x\n", old_date ); 
printf( "Old time field: @x%.4x\n", old_time ); 
system( "dir dgftime.obj" ); 


/* Modify file date and time */ 
if( !_dos_setftime( fh, new_date, new_time ) ) 


{ 
_dos_getftime( fh, &new_date, &new time ); 
printf( "New date field: @x%.4x\n", new_date ); 
printf( "New time field: @x%.4x\n", new_time ); 
system( “dir dgftime.obj" ); 
/* Restore date and time */ 
_dos_setftime( fh, old_date, old_time ); 

} 


_dos_close( fh ); 
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Output Old date field: Qx274f 
Old time field: @x94bb 


Volume in drive C is ZEPPELIN 
Directory of C:\LIBREF 


DGFTIME OBJ 3923 6-15-99 6:37p 
1 File(s) 13676544 bytes free 


New date field: Q@x26cf 
New time field: @x48eQ 


Volume in drive C is ZEPPELIN 
Directory of C:\LIBREF 


DGFTIME OBJ 3923 12-15-99 9:07a 
1 File(s) 13676544 bytes free 
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_dos_settime 
Description Sets the current system time, using system call 0x2D. 
#include <dos.h> 
unsigned _ dos_settime( struct _ dostime_t *time ); 


time New system time 


Remarks The _ dos_settime routine uses system call 0x2D to set the current system time to 
the value stored in the _dostime_t structure that time points to, as defined in 
DOS.H. The _ dostime_t structure contains the following elements: 


Element Description 
unsigned char hour OQ—23 
unsigned char minute 0-59 
unsigned char second O-59 
unsigned char hsecond Hundredths of a second; 0-99 
Return Value If successful, the function returns 0. Otherwise, it returns a nonzero value and sets 


errno to EINVAL, indicating an invalid time was specified. 


Compatibility Standards: None 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: None 
See Also _dos_ getdate, _dos_gettime, _dos_setdate, gmtime, localtime, mktime, 


_strdate, _strtime 
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Example /* DSTIME.C: This program changes the time and date values and displays the 
* new date and time values. 
* / 


d#Hinclude <dos.h> 
4#Hinclude <conio.h> 
#Hinclude <stdio.h> 
d#Hinclude <time.h> 


void main( void ) 


{ 


struct _dosdate_t olddate, newdate = { 
struct _dostime_t oldtime, newtime { 
char datebuf[40], timebuf[4@]; 


gd Te A OOD ae 
gt A ie TOP Te Oe 


/* Get current date and time values */ 

_dos_getdate( &olddate ); 

_dos_gettime( &oldtime ); 

printf( "%s 5\n" , _strdate( datebuf ), _strtime( timebuf ) ); 


/* Modify date and time structures */ 

_dos_setdate( &newdate ); 

_dos_settime( &newtime ); 

printf( "%s %4s\n" , _strdate( datebuf ), _strtime( timebuf ) ); 


/* Restore old date and time */ 
_dos_setdate( &olddate ); 
_dos_settime( &oldtime ); 


Output 12/15/99 18:26:09 
07/04/99 03:45:30 


Description 


Remarks 
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_dos_ setvect 


Sets the current value of the interrupt vector, using system call 0x25. 
#include <dos.h> 


void _ dos_setvect( unsigned intnum, 
void( __cdecl __ interrupt __ far *handler)()); 


inthum Target-interrupt vector 


handler Interrupt handler for which to assign intnum 


The _ dos_setvect routine uses system call 0x25 to set the current value of the in- 
terrupt vector intnum to the function pointed to by handler. Subsequently, when- 
ever the intnum interrupt is generated, the handler routine will be called. If 
handler is a C function, it must have been previously declared with the interrupt 
attribute. Otherwise, you must make sure that the function satisfies the require- 
ments for an interrupt-handling routine. For example, if handler is an assembler 
function, it must be a far routine that returns with an IRET instead of a RET. 


The interrupt attribute indicates that the function is an interrupt handler. The 
compiler generates appropriate entry and exit sequences for the interrupt-handling 
function, including saving and restoring all registers and executing an IRET in- 
struction to return. 


The _ dos_setvect routine is generally used with the _dos_ getvect function. To 
replace an interrupt vector, first save the current vector of the interrupt using 
_dos_ getvect. Then set the vector to your own interrupt routine with 
_dos_setvect. The saved vector can later be restored, if necessary, using 
_dos_setvect. The user-defined routine may also need the original vector in 
order to call it or to chain to it with _chain_ intr. 


Registers and Interrupt Functions 
When you call an interrupt function, the DS register is initialized to the C data seg- 
ment. This allows you to access global variables from within an interrupt function. 
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In addition, all registers except SS are saved on the stack. You can access these 
registers within the function if you declare a function parameter list containing a 
formal parameter for each saved register. The following example illustrates such a 
declaration: 


void __interrupt __far int_handler( unsigned _es, unsigned _ds, 
unsigned _di, unsigned _ si, 
unsigned _bp, unsigned _sp, 
unsigned _bx, unsigned _dx, 
unsigned _cx, unsigned _ax, 
unsigned _ip, unsigned _cs, 
unsigned _flags ) 


} 
The formal parameters must appear in the opposite order from which they are 
pushed onto the stack. You can omit parameters from the end of the list in a decla- 


ration, but not from the beginning. For example, if your handler needs to use only 
DI and SI, you must still provide ES and DS, but not necessarily BX or DX. 


You can pass additional arguments if your interrupt handler will be called directly 
from C rather than by an INT instruction. To do this, you must declare all register 
parameters and then declare your parameter at the end of the list. 


The compiler always saves and restores registers in the same, fixed order. Thus, 
no matter what names you use in the formal parameter list, the first parameter in 
the list refers to ES, the second refers to DS, and so on. If your interrupt routines 
will use inline assembler, you should distinguish the parameter names so that they 
will not be the same as the real register names. 


If you change any of the register parameters of an interrupt function while the 
function is executing, the corresponding register contains the changed value when 
the function returns. For example: 


void __interrupt __far int_handler( unsigned _es, unsigned _ds, 
unsigned _di, unsigned _si ) 


This code causes the DI register to contain —1 when the handler function returns. 
It is not a good idea to modify the values of the parameters representing the IP and 
CS registers in interrupt functions. If you must modify a particular flag (such as 
the carry flag for certain DOS and BIOS interrupt routines), use the OR operator 
(|) so that other bits in the flag register are not changed. 


Return Value 


Compatibility 


See Also 
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When an interrupt function is called by an INT instruction, the interrupt-enable 
flag is cleared. If your interrupt function needs to do significant processing, you 
should use the _ enable function to set the interrupt flag so that interrupts can be 
handled. 


Precautions for Interrupt Functions 

Since DOS is not reentrant (a DOS interrupt cannot be called from inside a DOS 
interrupt), it is usually not safe to call from inside an interrupt function any stand- 
ard library function that calls DOS INT 21H. Similar precautions apply to many 
BIOS functions. Functions that rely on INT 21H calls include I/O functions and 
the _dos family of functions. Functions that rely on the machine’s BIOS include 
graphics functions and the _ bios family of functions. It is usually safe to use func- 
tions that do not rely on INT 21H or BIOS, such as string-handling functions. 
Before using a standard library function in an interrupt function, be sure that you 
are familiar with the action of the library function. 


None. 


Standards: None 
16-Bit: DOS 
32-Bit: None 


_chain_intr, _dos_getvect, _dos_keep 
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Description 


Remarks 


Return Value 


Compatibility 


See Also 


_dos_ write 


Writes a buffer to a file, using system call 0x40. 
#include <dos.h> 


unsigned _dos_write( int handle, void __ far *buffer, unsigned count, 
unsigned *“numwrt ); 


handle File to write to 

buffer Buffer to write from 

count Number of bytes to write 
numwrt | Number of bytes actually written 


The _ dos_write routine uses system call 0x40 to write data to the file that handle 
references; count bytes of data from the buffer to which buffer points are written 
to the file. The integer pointed to by numwrt will be the number of bytes actually 
written, which may be less than the number requested. 


Do not use the DOS interface routines with the console, low-level, or stream I/O 
routines. 


If successful, the function returns 0. Otherwise, 1t returns the DOS error code and 
sets errno to one of the following manifest constants: 


Constant Meaning 
EACCES Access denied (handle references a file not open for write access) 
EBADF Invalid file handle 


Standards: None 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: None 


_dos_close, _dos_open, —dos_read, _ write 
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Example /* DWRITE.C: This program uses DOS I/0 functions to write to a file. */ 


#Hinclude <fcntl.h> 

#Hinclude <stdio.h> 

d#Finclude <stdlib.h> 
#Hinclude <dos.h> 


void main( void ) 

{ 
char out_buffer[L] = "Hello"; 
int fh; 
unsigned n_written; 


/* Open file with _dos_creat function */ 
if( _dos_creat( "data", _A NORMAL, &fh ) == @ ) 


{ 
/* Write data with _dos_write function */ 
_dos_write( fh, out_buffer, 5, &n_written ); 
printf( "Number of characters written: “4d\n", n_written ); 
_dos_close( fh ); 
printf( “Contents of file are:\n" ); 
System( "type data" ); 

I 

I 
Output Number of characters written: 5 


Contents of file are: 
Hello 


234 _ dosexterr 


_ dosexterr 


Description Gets register values returned by 0x59. 
#include <dos.h> 
int _dosexterr( struct _DOSERROR “errorinfo ); 


errorinfo Extended DOS error information 


Remarks The _ dosexterr function obtains the extended error information returned by DOS 
system call 0x59 and stores the values in the structure pointed to by errorinfo. 
This function 1s useful when making system calls with DOS versions 3.0 or later, 
which offer extended error handling. 


The structure type _DOSERROR is defined in DOS.H. The _DOSERROR 
structure contains the following elements: 


Element Description 

int exterror AX register contents 
char errclass BH register contents 
char action BL register contents 
char locus CH register contents 


Giving a NULL pointer argument causes _ dosexterr to return the value in AX 
without filling in the structure fields. See MS-DOS Encyclopedia (Duncan, ed.; 
Redmond, WA: Microsoft Press, 1988) or Programmer’s PC Sourcebook 2nd ed. 
(Hogan; Redmond, WA: Microsoft Press, 1991) for more information on the 
register contents. 


Return Value The _ dosexterr function returns the value in the AX register (identical to the 
value in the exterror structure field). 


Compatibility Standards: None 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: None 


The _ dosexterr function should be used only with DOS versions 3.0 or later. 


See Also 


Example 


Output 


_ dosexterr 


perror 


/* DOSEXERR.C: This program tries to open the file test.dat. 
* If the attempted open operation fails, the program uses 
* dosexterr to display extended error information. 


* / 


#tinclude 
#Finclude 
#tinclude 
#tinclude 


<dos.h> 
<i0.h> 
<fentl.h> 
<stdio.h> 


void main( void ) 


{ 


struct _DOSERROR doserror; 
ge a oem Ba 9 


/* Attempt to open a non-existent file */ 
if( (fd = _open( "NOSUCHF.ILE", _O_RDONLY )) == -1 ) 


{ 


_dosexterr( &doserror ); 
printf( "Error: 4d Errclass: %d Action: %4d Locus: %d\n", 


} 


else 


{ 


doserror.exterror, doserror.errclass, 
doserror.action, doserror.locus ); 


printf( "Open succeeded so no extended information printed\n" ); 
s6\oset id: 2s 


Error: 2 


Errclass: 8 Action: 3 Locus: 2 
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Description 


Remarks 


Return Value 


_dup, _dup2 


Create a second handle for an open file (_dup), or reassign a file handle (_dup2). 
#include <io.h> Required only for function declarations 


int _dup( int handle ); 


int _dup2( int handle 1, int handle2 ); 


handle, handle Handle referring to open file 
handle2 Any handle value 


The _dup and _dup2 functions cause a second file handle to be associated with a 
currently open file. Operations on the file can be carried out using either file 
handle. The type of access allowed for the file is unaffected by the creation of a 
new handle. 


The _ dup function returns the next available file handle for the given file. The 
_dup2 function forces handle2 to refer to the same file as handle1. If handle2 is 
associated with an open file at the time of the call, that file is closed. 


Note that in a QuickWin application you cannot use the _dup and _ dup2 func- 
tions on stdin, stdout, or stderr (defined in STDIO.H). You can, however, use the 
_dup and _dup2 functions on other handles. 


The _ dup function returns a new file handle. The _dup2 function returns 0 to indi- 
cate success. Both functions return —1 if an error occurs and set errno to one of 
the following values: 


Value Meaning 


EBADF Invalid file handle 
EMFILE No more file handles available (too many open files) 


Compatibility 


See Also 


Example 
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Standards: UNIX 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 


Use _dup and _dup2 for compatibility with ANSI naming conventions of non- 
ANSI functions. Use dup and dup2 and link with OLDNAMES.LIB for UNIX 
compatibility. 


_close, _ creat, _ open 


/* DUP.C: This program uses the variable old to save the original stdout. 
* It then opens a new file named new and forces stdout to refer 

* to it. Finally, it restores stdout to its original state. 

* / 


d#Ainclude <io.h> 
4#FHinclude <stdlib.h> 
d#Ainclude <stdio.h> 


void main( void ) 


{ 
int old; 
FILE *new; 
old = _dup( 1 ); /* “old" now refers to “stdout” */ 
/* Note: file handle 1 == "stdout" */ 
if€ old == -1 ) 
{ 


perror( "_dup( 1 ) failure" ); 

exit( 1 ); 
} 
write( old, "This goes to stdout first\r\n", 27 ); 
if( ( new = fopen( "data", "w" ) ) == NULL ) 


{ 
puts( "Can't open file ‘data’\n" ); 
exit( 1 ); 
} 
/* stdout now refers to file "data" */ 
if( -1 == _dup2( _fileno( new ), 1 ) ) 
{ 


perror( "Can't _dup2 stdout" ); 
exit( 1 ); 

} 

puts( "This goes to file ‘data'\r\n" ); 


/* Flush stdout stream buffer so it goes to correct file */ 
fflush( stdout ); 
fclose( new ); 
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/* Restore original stdout */ 

_dup2( old, 1 ); 

puts( "This goes to stdout\n" ); 
puts( "The file 'data' contains:" ); 
system( "type data" ); 


Output This goes to stdout first 
This goes to stdout 


The file ‘data’ contains: 
This goes to file ‘data’ 
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_ ecvi 
Description Converts a double number to a string. 


#include <stdlib.h> Required only for function declarations 


char *_ecvt( double value, int count, int *dec, int *sign ); 


value Number to be converted 
count Number of digits stored 
dec Stored decimal-point position 
sign Sign of converted number 
Remarks The _ eevt function converts a floating-point number to a character string. The 


value argument is the floating-point number to be converted. The _ eevt function 
stores up to count digits of value as a string and appends a null character (’\0’). If 
the number of digits in value exceeds count, the low-order digit is rounded. If 
there are fewer than count digits, the string is padded with zeros. 


Only digits are stored in the string. The position of the decimal point and the sign 
of value can be obtained from dec and sign after the call. The dec argument points 
to an integer value giving the position of the decimal point with respect to the 
beginning of the string. A 0 or negative integer value indicates that the decimal 
point lies to the left of the first digit. The sign argument points to an integer indi- 
cating the sign of the converted number. If the integer value is 0, the number is 
positive. Otherwise, the number is negative. 


The _eevt and _fevt functions use a single statically allocated buffer for the con- 
version. Each call to one of these routines destroys the result of the previous call. 


Return Value The _ eevt function returns a pointer to the string of digits. There is no error return. 
Compatibility Standards: UNIX 

16-Bit: DOS, QWIN, WIN, WIN DLL 

32-Bit: DOS32X 


Use _ ecvt for compatibility with ANSI naming conventions of non-ANSI func- 
tions. Use ecvt and link with OLDNAMES.LIB for UNIX compatibility. 


See Also atof, atoi, atol, _ fevt, _ gcvt 
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Example /* ECVT.C: This program uses _ecvt to convert a floating-point 
* number to a character string. 
* / 


d#Hinclude <stdlib.h> 
#Hinclude <stdio.h> 


void main( void ) 


if 
int decimal, sign; 
char «buffer; 
int precision = 19; 
double source = 3.1415926535; 
buffer = _ecvt( source, precision, &decimal, &sign ); 
printf( “source: %42.10f buffer: '%s' decimal: 4d Sign: 4d\n", 
source, buffer, decimal, sign ); 
} 


Output source: 3.1415926535 buffer: '3141592654' decimal: 1 Sign: @ 


Description 


Remarks 


_ ellipse Functions 241 


_ ellipse Functions 


Draw ellipses. 
#include <graph.h> 


short __ far _ ellipse( short control, short x/, short y/, short x2, short y2 ); 


short __ far _ ellipse_w( short control, double wx/, double wy/, double wx2, 
double wy2 ); 


short __ far _ellipse_wxy( short control, struct _ wxycoord __ far *pwxy/, 
struct _ wxycoord __ far *pwxy2 ); 


control Fill flag 

xl,yl Upper-left corner of bounding rectangle 

5 Ae Lower-right corner of bounding rectangle 
wxl, wyl Upper-left corner of bounding rectangle 
wx2, wy2 Lower-right corner of bounding rectangle 
pwxyl Upper-left corner of bounding rectangle 
pwxy2 Lower-right corner of bounding rectangle 


The _ ellipse functions draw ellipses or circles. The borders are drawn in the cur- 
rent color. In the _ ellipse function, the center of the ellipse is the center of the 
bounding rectangle defined by the view-coordinate points (x/, y/) and (x2, y2). 


In the _ ellipse_ w function, the center of the ellipse is the center of the bounding 
rectangle defined by the window-coordinate points (wx/, wy/) and (wx2, wy2). 


In the _ ellipse_ wxy function, the center of the ellipse is the center of the bound- 
ing rectangle defined by the window-coordinate points (pwxy/) and (pwxy2). 


If the bounding-rectangle arguments define a point or a vertical or horizontal line, 
no figure is drawn. 
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The control argument can be one of the following manifest constants: 


Constant Action 
_GFILLINTERIOR _ Uses _floodfill to fill the ellipse using the current fill mask 
_GBORDER Does not fill the ellipse 


The control option given by _GFILLINTERIOR is equivalent to a subsequent 
call to the _ floodfill function, using the center of the ellipse as the starting point 
and the current color (set by _setcolor) as the boundary color. 


Return Value The _ ellipse functions return a nonzero value if the ellipse is drawn successfully; 
otherwise, they return 0. 


Compatibility Standards: None 
16-Bit: DOS 
32-Bit: None 
See Also _arc functions, _ floodfill, _grstatus, _lineto functions, _pie functions, 


_ polygon functions, _rectangle functions, _setcolor, _setfillmask 


Example /* ELLIPSE.C: This program draws a simple ellipse. */ 


4#Finclude <conio.h> 
#Finclude <stdlib.h> 
fHinclude <graph.h> 


void main( void ) 
{ 
/* Find a valid graphics mode. */ 
if( ! setvideomode( _MAXRESMODE ) ) 
exit( 1 ); 


_ellipse( _GFILLINTERIOR, 80, 50, 240, 150 ); 


/* Strike any key to clear screen. */ 
_getch(); 
_setvideomode( _DEFAULTMODE ); 

} | 


Description 


Remarks 


Return Value 


Compatibility 


See Also 


_ enable 


Enables interrupts. 


#include <dos.h> 


void _ enable( void ); 


The _ enable routine enables interrupts by executing an 8086 STI machine 


instruction. 


None. 


Standards: 
16-Bit: 
32-Bit: 


_ disable 


None 
DOS, QWIN, WIN, WIN DLL 


None 


_ enable 
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_ eof 


Description Tests for end-of-file. 
#include <io.h> Required only for function declarations 
int _ eof( int handle ); 


handle Handle referring to open file 

Remarks The _ eof function determines whether the end of the file associated with handle 
has been reached. 

Return Value The _ eof function returns the value 1 if the current position is end-of-file, or 0 if it 
is not. A return value of —1 indicates an error; in this case, errno is set to EBADF, 


indicating an invalid file handle. 


Compatibility Standards: None 


16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 
See Also clearerr, feof, ferror, perror 


Example /* EOF.C: This program reads data from a file ten bytes at a time 
* until the end of the file is reached or an error is encountered. 
* / 


#Finclude <io.h> 
#Finclude <fcntl.h> 
#Finclude <stdio.h> 
#Hinclude <stdlib.h> 


Output 


_ eof 


void main( void ) 


i 


int fh, count, total = Q@; 
char buf[10]; 


11. (GPh =2 open “eofsc” 2O-RDONLY jo e== 2 9 
exit( 1 ); 

/* Cycle until end of file reached: */ 

while( !_eof( fh ) ) 


{ 
/* Attempt to read in 10 bytes: */ 
if( (count = _read( fh, buf, 10 )) == -l ) 
{ 
perror( "Read error" ); 
break; 
j 
/* Total up actual bytes read */ 
total += count; 
I 


printf( "Number of bytes read = 4d\n", total ); 
_close( fh ); 


Number of bytes read = 715 
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—_ exec Functions 


Description Load and execute new child processes. 
#include <process.h> Required only for function declarations 


int _ execl( char *cmdname, char *arg0, ... char “argn, NULL ); 

int _ execle( char *cmdname, char *arg0, ... char *argn, NULL, char **enyp ); 
int _ execlp( char *cmdname, char *arg0, ... char *argn, NULL ); 

int _execlpe( char *cmdname, char *arg0, ... char *argn, NULL, char **envp _); 
int _execv( char *cmdname, char **argv ); 

int _ execve( char *cmdname, char **argv, char **envp ); 

int _execvp( char *cmdname, char **argy ); 


int _execvpe( char *cmdname, char **argy, char **envp ); 


cmdname Path name of file to be executed 

arg0, ... argn List of pointers to arguments 

argy Array of pointers to arguments 

envp Array of pointers to environment settings 
Remarks The _ exec functions load and execute new child processes. When the call is 


successful in DOS, the child process is placed in the memory previously occupied 
by the calling process. Sufficient memory must be available for loading and ex- 
ecuting the child process. 


All of the _ exec functions use the same operating system function. The letter(s) at 
the end of the function name determine the specific variation, as shown in the 
following list: 
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Letter Variation 

e An array of pointers to environment arguments is explicitly passed to 
the child process. 

] Command-line arguments are passed individually to the _ exec 
function. 

p Uses the PATH environment variable to find the file to be executed. 

Vv Command-line arguments are passed to the _ exec function as an 


array of pointers. 


The cmdname argument specifies the file to be executed as the child process. It 
can specify a full path (from the root), a partial path (from the current working 
directory), or just a filename. If cmdname does not have a filename extension or 
does not end with a period (.), the _ exec function searches for the named file; if 
the search 1s unsuccessful, it tries the same base name, first with the extension 
.COM, then with the extension .EXE. If cmdname has an extension, only that ex- 
tension is used in the search. If cmdname ends with a period, the _ exec calls 
search for cmdname with no extension. The _execlp, _ execlpe, _execvp, and 
_execvpe routines search for cmdname (using the same procedures) in the directo- 
ries specified by the PATH environment variable. 


If cmdname contains a drive specifier or any slashes (that is, if it is a relative path 
name), the _ exec call searches only for the specified file; the path is not searched. 
Note that the DOS APPEND command cannot be used with the _ exec functions. 


Arguments are passed to the new process by giving one or more pointers to charac- 
ter strings as arguments in the _ exec call. These character strings form the argu- 
ment list for the child process. The combined length of the strings forming the 
argument list for the new process must not exceed 128 bytes (in real mode only). 
The terminating null character (’\0’) for each string is not included in the count, 
but space characters (inserted automatically to separate the arguments) are counted. 


The argument pointers can be passed as separate arguments (_ execl, _ execle, 
_execlp, and _ execlpe) or as an array of pointers (_ execv, _ execve, _ execvp, and 
_execvpe). At least one argument, arg0, must be passed to the child process; this 
argument is argv[Q] of the child process. Usually, this argument is a copy of the 
cmdname argument. (A different value will not produce an error.) Under versions 
of DOS earlier than 3.0, the passed value of arg0 is not available for use in the 
child process. However, with DOS versions 3.0 and later, cmdname is available as 
arg0. 


The _ execl, _ execle, _ execlp, and _execlpe calls are typically used when the 
number of arguments is known in advance. The argument arg0 is usually a pointer 
to cmdname. The arguments arg/ through argn point to the character strings form- 
ing the new argument list. A null pointer must follow argn to mark the end of the 
argument list. 
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The _execv, _ execve, _ execvp, and _ execvpe calls are useful when the number 
of arguments to the new process is variable. Pointers to the arguments are passed 
as an array, argv. The argument argv[0] is usually a pointer to cmdname. The argu- 
ments argv[1] through argv[n] point to the character strings forming the new argu- 
ment list. The argument argv[n+1] must be a NULL pointer to mark the end of the 
argument list. 


Files that are open when an _ exec call is made remain open in the new process. In 
the _execl, _ execlp, _ execv, and _ execvp calls, the child process inherits the en- 
vironment of the parent. The _ execle, _ execlpe, _ execve, and _ execvpe calls 
allow the user to alter the environment for the child process by passing a list of en- 
vironment settings through the envp argument. The argument envp 1s an array of 
character pointers, each element of which (except for the final element) points to a 
null-terminated string defining an environment variable. Such a string usually has 
the form 


NAME=value 


where NAME is the name of an environment variable and value is the string value 
to which that variable is set. (Note that value is not enclosed in double quotation 
marks.) The final element of the envp array should be NULL. When envp itself is 
NULL, the child process inherits the environment settings of the parent process. 


A program executed with one of the _ exec family of functions is always loaded 
into memory as if the “maximum allocation” field in the program’s .EXE file 
header is set to the default value of OxFFFFH. You can use the EXEHDR utility to 
change the maximum allocation field of a program; however, such a program in- 
voked with one of the _ exec functions may behave differently from a program in- 
voked directly from the operating-system command line or with one of the 
_spawn functions. i | 7 


Note that COMMAND.COM checks the first two bytes of a file to determine 
whether it is an .EXE file or a .COM file—you can execute a file named by any ex- 
tension, as long as its content is truly executable. 


The _ exec calls do not preserve the translation modes of open files. If the child 
process must use files inherited from the parent, the _setmode routine should be 
used to set the translation mode of these files to the desired mode. 


You must explicitly flush (using fflush or _flushall) or close any stream prior to 
the _ exec function call. 


Signal settings are not preserved in child processes that are created by calls to 
_exec routines. The signal settings are reset to the default in the child process. 


Return Value 


Compatibility 


See Also 


Example 


/* 
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The _ exec functions do not normally return to the calling process. If an _exec 
function returns, an error has occurred and the return value is —1. The errno varia- 
ble is set to one of the following values: 


Value Meaning 

E2BIG | The argument list exceeds 128 bytes, or the space required for 
the environment information exceeds 32K. 

EACCES The specified file has a locking or sharing violation (DOS 
version 3.0 or later). 

EMFILE Too many files open (the specified file must be opened to 
determine whether it is executable). 

ENOENT File or path name not found. 

ENOEXEC The specified file is not executable or has an invalid executable- 


file format. 


ENOMEM Not enough memory 1s available to execute the child process; or 
the available memory has been corrupted; or an invalid block 
exists, indicating that the parent process was not allocated 


properly. 
Standards: UNIX 
16-Bit: DOS 
32-Bit: DOS32X 


Use _ exec for compatibility with ANSI naming conventions of non-ANSI func- 
tions. Use exec and link with OLDNAMES.LIB for UNIX compatibility. 


Because of differences in DOS versions 2.0 and 2.1, child processes generated by 
the _ exec family of functions (or by the equivalent _ spawn functions with the 
_P_OVERLAY argument) may cause fatal system errors when they exit. If you 
are running DOS 2.0 or 2.1, you must upgrade to DOS version 3.0 or later to use 
these functions. 


Bound programs cannot use the _ exec family of functions in real mode. 


abort, atexit, exit, _ exit, _ onexit, _ spawn functions, system 


EXEC.C: This program accepts a number in the range 1 through 8 from the 


* command line. Based on the number it receives, it executes one of the 
* eight different procedures that spawn the process named child. For 

* Some of these procedures, the child.exe file must be in the same 

* directory; for others, it need only be in the same path. 


* / 


#Hinclude <stdio.h> 
#Hinclude <process.h> 
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char *my_env[L] = { 
"THIS=environment will be", 
"PASSED=to child.exe by the", 
" EXECLE=and", 
" EXECLPE=and", 
" EXECVE=and", 
" EXECVPE=functions", 
NULL 
Le 


‘void main( int argc, char *argv[] ) 
f | 

char *args[4]; 

int result; 


args[Q@] "child"; /* Set up parameters to send */ 
args[1] " execv??"; 

args[2] "two"; 

args[3] NULL; 


switch( argvL1][@] ) /* Based on first letter of argument */ 
{ 
case 'l': 
—~execl( argv[2], argv[2], "_execl", "two", NULL ); 
break; 
case '2': 
_execle( argv[2], argv[2], "_execle", "two", NULL, my_env ); 
break; 
Gases 
_execlp( argv[2], argv[2], "_execlp", "two", NULL ); 
break; ! 
case ‘4': 
_execlpe( argv[2], argv[2], "_execlpe”", "two", NULL, my_env ); 
breaks. 
case ‘5': 
_execv( argv[2], args ); 
break; 
case ‘'6': 
_execve( argv[2], args, my_env ); 
break; 
case ‘'/': 
_execvp( argv[2], args ); 
break; 
case ‘8': 
_execvpe( argv[2], args, my_env ); 
break; 
default: 
printf( "SYNTAX: EXEC <1-8> <childprogram>\n" ); 
7 exit¢( 1 ); 
j : - 
printf( "Process was not spawned.\n" ); 
printf( "Program ‘child’ was not found." ); 
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exit, exit 


Description Terminate the calling process after cleanup (exit) or immediately ( _ exit). 
#include <process.h> Required only for function declarations 
#include <stdlib.h> Use either PROCESS.H or STDLIB.H 


void exit( int status ); 


void _ exit( int status ); 


status Exit status 


Remarks The exit and _ exit functions terminate the calling process. The exit function first 
calls, in LIFO (last-in—first-out) order, the functions registered by atexit and 
_onexit, then flushes all file buffers before terminating the process. The _ exit 
function terminates the process without processing atexit or _ onexit functions or 
flushing stream buffers. The status value is typically set to 0 to indicate a normal 
exit and set to some other value to indicate an error. 


Although the exit and _ exit calls do not return a value, the low-order byte of 
status 1s made available to the waiting parent process, if one exists, after the 
calling process exits. The status value 1s available to the operating-system batch 
command ERRORLEVEL. 


The behavior of the exit, _ exit, _ cexit, and _ c_exit functions is as follows: 


Function Action 
exit Performs complete C library termination procedures, terminates 
the process, and exits with the supplied status code. 


_ exit Performs “quick” C library termination procedures, terminates 
the process, and exits with the supplied status code. 


_cexit Performs complete C library termination procedures and returns 
to caller, but does not terminate the process. 


_c_exit Performs “quick” C library termination procedures and returns 
to caller, but does not terminate the process. 


Return Value None. 
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Compatibility exit 
Standards: ANSI, UNIX 
16-Bit: DOS, QWIN, WIN 
32-Bit: DOS32X 
_ exit 


Standards: None 


16-Bit: DOS, QWIN, WIN- 
32-Bit: DOS32X 
See Also abort, atexit, _ cexit, _ exec functions, _ onexit, _ spawn functions, system 


Example /* EXITER.C: This program prompts the user for a yes or no and returns 
* a DOS error code of 1 if the user answers Y or y; otherwise it 
* returns @. The error code could be tested in a batch file. 
* / 


d#Einclude <conio.h> 
#Hinclude <stdlib.h> 


void main( void ) 
{ 
char. ch; 


Cputs¢ “Yes or no?:*): 
Ch = --getch():: 
-Couts “Ven 
if( toupper( ch ) == 'Y" ) 
exit( 1 ); 
else 
exit( @ ); 
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exp, expl 


Description Calculate the exponential. 
#include <math.h> 


double exp( double x ); 
long double _ expl( long double x ); 


x Floating-point value 


Remarks The exp and _ expl functions return the exponential function of their floating-point 
arguments (x). 


The _expl function is the 80-bit counterpart; it uses an 80-bit, 10-byte coprocessor 
form of arguments and return values. See the reference page on the long double 
functions for more details on this data type. 


Return Value These functions return e*. The functions return HUGE_VAL on overflow and set 
errno to ERANGE; on underflow, they return O but do not set errno. This be- 
havior can be changed with the _matherr function. 


Compatibility exp 
Standards: ANSI, UNIX 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 
_expl 
Standards: None 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: None 


See Also log functions 
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Example /* EXP.C */ 
#Hinclude <math.h> 
d#Finclude <stdio.h> 


void main( void ) 


\ 

double x = 2.302585093, y; 

y = exp( x ); 

printf( "exp( “f ) = “2f\n", x, y ); 
j 


Output exp( 2.302585 ) = 10.000000 


Description 


Remarks 
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_ expand Functions 


Change the size of a memory block. 


#include <malloc.h> Required only for function declarations 


void *_expand( void *memblock, size_t size ); 


void __ based( void ) *_bexpand( ___ segment seg, 
void __ based( void ) *memblock, size_t size )3 


void __ far *_fexpand( void __ far *memblock, size_t size ); 


void __ near *_nexpand( void __ near *memblock, size_t size ); 


memblock Pointer to previously allocated memory block 
size New size in bytes 
seg Value of base segment 


The _ expand family of functions changes the size of a previously allocated 
memory block by attempting to expand or contract the block without moving its lo- 
cation in the heap. The memblock argument points to the beginning of the block. | 
The size argument gives the new size of the block, in bytes. The contents of the 
block are unchanged up to the shorter of the new and old sizes. 


The memblock argument can also point to a block that has been freed, as long as 
there has been no intervening call to calloc, _ expand, malloc, or realloc. If 
memblock points to a freed block, the block remains free after a call to one of the 
_ expand functions. 


The seg argument is the segment address of the __ based heap. 


In large data models (compact-, large-, and huge-model programs), _ expand 
maps to _fexpand. In small data models (tiny-, small-, and medium-model pro- 
grams), _expand maps to _nexpand. 
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Return Value 


Compatibility 


See Also 


The various _ expand functions change the size of the storage block in the data 
segments shown in the list below: 


Function Data Segment 

_ expand Depends on data model of program 

__bexpand Based heap specified by seg, or in all based heaps if seg is zero 
_fexpand Far heap (outside default data segment) 

_nexpand Near heap (inside default data segment) 


The _ expand family of functions returns a void pointer to the reallocated memory 
block. Unlike realloc, _ expand cannot move a block to change its size. This 
means the memblock argument to _ expand is the same as the return value if there 
is sufficient memory available to expand the block without moving it. 


With the exception of the _ bexpand function, these functions return NULL if 
there is insufficient memory available to expand the block to the given size 
without moving it. The _ bexpand function returns _NULLOFF if insufficient 
memory is available. The item pointed to by memblock will have been expanded 
as much as possible in its current location. 


The storage space pointed to by the return value is guaranteed to be suitably 
aligned for storage of any type of object. The new size of the item can be checked 
with one of the _msize functions. To get a pointer to a type other than void, use a 
type cast on the return value. 


_ expand 

Standards: None 

16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 


_bexpand, _ fexpand, _ nexpand 
Standards: None 

16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: None 


calloc functions, free functions, malloc functions, _ msize functions, realloc 
functions 


Example 


Output 


_ expand Functions 


/* EXPAND.C */ 

#Hinclude <stdio.h> 
d#Hinclude <malloc.h> 
#Hinclude <stdlib.h> 


void main( void ) 


{ 


char *bufchar; 


printf( "Allocate a 512 element buffer\n" ); 
if( (bufchar = (char *)calloc( 512, sizeof( char ) )) == NULL ) 
exit( 1 ); 
printf( "Allocated 4d bytes at %Fp\n", 
_msize( bufchar ), (void __far *)bufchar ); 


if( (bufchar = (char *)_expand( bufchar, 1024 )) == NULL ) 
printf( "Can't expand" ); 
else 
printf( "Expanded block to %d bytes at %Fp\n", 
_msize( bufchar ), (void __far *)bufchar ); 


/* Free memory */ 
free( bufchar ); 
exit( @ ); 


Allocate a 512 element buffer 
Allocated 512 bytes at 0067:142A 
Expanded block to 1024 bytes at 0067:142A 
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Description 


Remarks 


Return Value 


Compatibility 


See Also 


fabs, _ fabsl 


Calculate the absolute value of their floating-point arguments. 
#include <math.h> 


double fabs( double x ); 


long double _fabsl( long double x ); 


x Floating-point value 


The fabs and _ fabsl functions calculate the absolute value of their floating-point 
arguments. 


The _fabsl function is the 80-bit counterpart; it uses an 80-bit, 10-byte coproces- 
sor form of arguments and return values. See the reference page on the long 
double functions for more details on this data type. 


These functions return the absolute value of their arguments. There is no error 
return. 


fabs 

Standards: ANSI, UNIX 

16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 

_fabsl | 

Standards: None 

16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: None 


abs, _ cabs, labs 
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Example /* ABS.C: This program computes and displays the absolute values of 
* several numbers. 
* / 


d#tinclude <stdio.h> 
dtinclude <math.h> 
deinclude <stdlib.h> 


void main( void ) 

{ 
int ix = -4, ly; 
long Ix S HAT SG 7s, Tye 
double dx -~3.141593, dy; 


Ty =: ans 1% )8 
printf( "The absolute value of %d is %4d\n", ix, iy); 


Ly = Tabs Ctx) 
printf( “The absolute value of 41d is 41d\n", 1x, ly); 


dy = fabs( dx ); 
printf( "The absolute value of %f is %f\n", dx, dy ); 


Output The absolute value of -4 is 4 
The absolute value of -41567 is 41567 
The absolute value of -3.141593 is 3.141593 
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Description 


Remarks 


Return Value 


Compatibility 


See Also 


fclose, _fcloseall 


Closes a stream (fclose) or closes all open streams (_ fcloseall). 
#include <stdio.h> 


int fclose( FILE *stream ); 


int _ fcloseall( void ); 


stream Pointer to FILE structure 


The fclose function closes stream. The _fcloseall function closes all open streams 
except stdin, stdout, stderr (and in DOS, stdaux and stdprn). It also closes and 
deletes any temporary files created by tmpfile. 


In both functions, all buffers associated with the stream are flushed prior to clos- 
ing. System-allocated buffers are released when the stream is closed. Buffers as- 
signed by the user with setbuf and setvbuf are not automatically released. 


The fclose function returns 0 if the stream is successfully closed. The _ fcloseall 
function returns the total number of streams closed. Both functions return EOF to 
indicate an error. 


fclose 

Standards: ANSI, UNIX 

16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 

_fcloseall 


Standards: None 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 


_close, _fdopen, fflush, fopen, freopen 


Example 


Output 


/* FOPEN.C: This program opens files named "data" and “data2". It uses 
* fclose to close "data" and _fcloseall to close all remaining files. 


* / 


fclose, _fcloseall 


dAinclude <stdio.h> 


FILE *stream, *stream2; 


void main( void ) 


{ 


int numclosed; 


/* Open for read (will fail if ‘data does not exist) */ 
if( (stream = fopen( "data", "r" )) == NULL ) 

printf( "The file ‘data’ was not opened\n"™ ); 
else 

printf( "The file 'data' was opened\n" ); 


/* Open for write */ 
if( (stream2 = fopen( "data2", "wt" )) == NULL ) 
printf( "The file ‘data2" was not opened\n" ); 
else 
printf( "The file 'data2" was opened\n" ); 


/* Close stream */ 
if( fclose( stream ) ) 
printf( "The file ‘data"' was not closed\n" ); 


/* All other files are closed: */ 
numclosed = _fcloseall( ); 


printf( "Number of files closed by _fcloseall: Zu\n", numclosed ); 


The file ‘data’ was opened 
The file 'data2" was opened 
Number of files closed by _fcloseall: 1 
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Description 


Remarks 


Return Value 


Compatibility 


_ fevt 


Converts a floating-point number to a string. 
#include <stdlib.h> Required only for function declarations 


char *_fevt( double value, int count, int *dec, int *sign ); 


value Number to be converted 

count Number of digits after decimal point 
dec Pointer to stored decimal-point position 
sign Pointer to stored sign indicator 


The _fevt function converts a floating-point number to a null-terminated character 
string. The value argument is the floating-point number to be converted. The _fevt 
function stores the digits of value as a string and appends a null character (’\0’). 
The count argument specifies the number of digits to be stored after the decimal 
point. Excess digits are rounded off to count places. If there are fewer than count 
digits of precision, the string is padded with zeros. 


Only digits are stored in the string. The position of the decimal point and the sign 
of value can be obtained from dec and sign after the call. The dec argument points 
to an integer value; this integer value gives the position of the decimal point with 
respect to the beginning of the string. A zero or negative integer value indicates 
that the decimal point lies to the left of the first digit. The argument sign points to 
an integer indicating the sign of value. The integer is set to 0 1f value is positive 
and is set to a nonzero number if value is negative. 


The _ecvt and _fevt functions use a single statically allocated buffer for the con- 
version. Each call to one of these routines destroys the results of the previous call. 


The _fevt function returns a pointer to the string of digits. There is no error return. 


Standards: UNIX 
16-Bit: DOS, QWIN, WIN, WIN’DLL 
32-Bit: DOS32X 


Use _fevt for compatibility with ANSI naming conventions of non-ANSI func- 
tions. Use fevt and link with OLDNAMES.LIB for UNIX compatibility. 


See Also 


Example 


Output 
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atof, atoi, atol, _ ecvt, _ gcvt 


/* FCVT.C: This program converts the constant 3.1415926535 to a string and 
* sets the pointer *buffer to point to that string. 
* / 


dEinclude <stdlib.h> 
#Hinclude <stdio.h> 


void main( void ) 


{ 
int decimal, sign; 
char *buffer; 
double source = 3.1415926535; 
buffer = _fcvt( source, 7, &decimal, &sign ); 
printf( “source: %42.10f buffer: '"%s' decimal: %d Sign: 4d\n", 
source, buffer, decimal, sign ); 
} 


source: 3.1415926535 buffer: '31415927' decimal: 1 sign: Q 
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Description 


Remarks 


_fdopen 


Associates a stream with a file that was previously opened for low-level I/O. 
#include <stdio.h> 
FILE *_fdopen( int handle, char *mode ); 


handle Handle referring to open file 


mode Type of access permitted 


The _ fdopen function associates an input/output stream with the file identified by 
handle, thus allowing a file opened for low-level I/O to be buffered and formatted. 
(For an explanation of stream I/O and low-level I/O see “Input and Output” on 
page 31.) The mode character string specifies the type of access requested for the 
file, as shown below. The following list gives the mode string used in the fopen 
and _ fdopen functions and the corresponding oflag arguments used in the _ open 
and _sopen functions. A complete description of the mode string argument is 
given in the remarks section of the fopen function. 


Type String Equivalent Value for _ open/_sopen 

ie Gs _O_RDONLY 

"w" _O_WRONLY (usually _O-~WRONLY |__O_ CREAT | 
_O_TRUNC) 

"al _O_WRONLY | _O_ APPEND (usually _O_WRONLY | 
_O_CREAT |_O_ APPEND) 

i ce ~O_RDWR ae 

oe _O_RDWR (usually _O_ RDWR | _O_CREAT | 
_O_TRUNC) 

"at" _O_RDWR |_O_APPEND (usually _O_ RDWR | 


_O_APPEND | _O_ CREAT ) 


In addition to the values listed above, one of the following characters can be in- 
cluded in the mode string to specify the translation mode for new lines. These char- 
acters correspond to the constants used in the _ open and _sopen functions, as 
shown below: 


Mode Equivalent Value for _ open/_sopen 


t _O_TEXT 
b _O_BINARY 


Return Value 
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If t or b is not given in the mode string, the translation mode is defined by the 
default-mode variable _fmode. 


In addition to the file attribute and the text or binary mode listed above, the mode 
string accepts either ¢ or n to specify commit to disk, or do not commit to disk, re- 
spectively. These characters have no correspondence to constants used in the 
_open and _sopen functions. For more information on the commit feature, see 
“Committing Buffer Contents to Disk” on page 3737. 


Mode Description 
c Commit to disk, no _ open/_sopen equivalent. 
n No commit, no _open/_sopen equivalent. Default. 


If c or n is not given in the mode string, n is the default mode. 


The _fdopen function returns a pointer to the open stream. A null pointer value in- 
dicates an error. 


Compatibility Standards: UNIX 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 


See Also 


Example 


Use _fdopen for compatibility with ANSI naming conventions of non-ANSI func- 
tions. Use fdopen and link with OLDNAMES.LIB for UNIX compatibility. 


The t, c, and n options are not part of the ANSI standard for fopen and _ fdopen, 
but are instead Microsoft extensions and should not be used where ANSI portabil- 
ity is desired. 


_dup, _dup2, fclose, _ fcloseall, fopen, freopen, _ open 


/* _FDOPEN.C: This program opens a file using low-level I/0, then uses 
* fdopen to switch to stream access. It counts the lines in the file. 
* / 


#Finclude <stdlib.h> 
dFHinclude <stdio.h> 
#Hinclude <fcntl.h> 
#tinclude <io.h> 
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void main( void ) 

{ 
FILE *stream; 
int fh, count = @; 
char inbuf[128]; 


/* Open a file handle. */ 

if( (fh = _open( "_fdopen.c", _O_RDONLY )) == -1 ) 
exit( 1 ); 

/* Change handle access to stream access. */ 

if( (stream = _fdopen( fh, "r" )) == NULL ) 
exit( 1 ); 


while( fgets( inbuf, 128, stream ) != NULL ) 
COUNT+t: 


/*x After _fdopen, close with fclose, not _close. */ 
fclose( stream ); 


printf( “Lines in file: %4d\n", count ); 


Output Lines in file: 31 
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feof 


Description Tests for end-of-file on a stream. 
#include <stdio.h> 
int feof( FILE *stream ); 


stream Pointer to FILE structure 


Remarks The feof routine (implemented both as a function and as a macro) determines 
whether the end of stream has been reached. Once the end of the file is reached, 
read operations return an end-of-file indicator until the stream is closed or until 
rewind, fsetpos, fseek, or clearerr is called against it. 


Return Value The feof function returns a nonzero value after the first read operation that at- 
tempts to read past the end of the file. It returns O if the current position is not end- 
of-file. There is no error return. 


Compatibility Standards: ANSI, UNIX 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 

See Also clearerr, _ eof, ferror, perror 


Example /* FEOF.C: This program uses feof to indicate when it reaches the end 
* of the file FEOF.C. It also checks for errors with ferror. 
* / 


d#Ainclude <stdio.h> 
#Ainclude <stdlib.h> 
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void main( void ) 
{ : 
int count, total = Q; 
char buffer[l100]; 

FILE *stream; 


if( (stream = fopen( "feof.c", "r" )) == NULL ) 
exit( 1 ); 


/* Cycle until end of file reached: */ 
while( !feof( stream ) ) 


a 
/* Attempt to read in 10 bytes: */ 
count = fread( buffer, sizeof( char ), 100, stream ); 
if( ferror( stream ) ) 
{ 
perror( "Read error" ); 
break; 
Ns 
/* Total up actual bytes read */ 
total += count; 
} 


printf( "Number of bytes read = 4d\n", total ); 
fclose( stream ); 


Output Number of bytes read = 697 


Description 


Remarks 


Return Value 


Compatibility 


See Also 


Example 
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ferror 
Tests for an error on a Stream. 
#include <stdio.h> 
int ferror( FILE *stream ); 


stream Pointer to FILE structure 


The ferror routine (implemented both as a function and as a macro) tests for a 


reading or writing error on the file associated with stream. If an error has oc- 
curred, the error indicator for the stream remains set until the stream is closed or 
rewound, or until clearerr is called against it. 


If no error has occurred on stream, ferror returns 0. Otherwise, it returns a non- 
zero value. 


Standards: ANSI, UNIX 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 


clearerr, _ eof, feof, fopen, perror 


/* FEOF.C: This program uses feof to indicate when it reaches the end 
* of the file FEOF.C. It also checks for errors with ferror. 


dAinclude <stdio.h> 
d4Einclude <stdlib.h> 
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void main( void ) 


{ 
int count, total = Q; 
char buffer[100]; 
FILE *stream; 
if( (stream = fopen( "feof.c", "r" )) == NULL ) 
exit( 1 ); 
/* Cycle until end of file reached: */ 
while( !feof( stream ) ) 
{ 
/* Attempt to read in 10 bytes: */ 
count = fread( buffer, sizeof( char ), 100, stream ); 
if( ferror( stream ) ) 
1 
perror( "Read error" ); 
break; 
} 
/* Total up actual bytes read */ 
Total -F=-Ccount: 
} 
printf( “Number of bytes read = %d\n", total ); 
fclose( stream ); 
} 


Output Number of bytes read = 697 


Description 


Remarks 


Return Value 


Compatibility 


See Also 
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fflush 


Flushes a stream. 
#include <stdio.h> 
int fflush( FILE *stream ); 


stream Pointer to FILE structure 


If the file associated with stream is open for output, fflush writes to that file the 
contents of the buffer associated with the stream. If the stream is open for input, 
fflush clears the contents of the buffer. The fflush function negates the effect of 
any prior call to ungetc against stream. 


Buffers are automatically flushed when they are full, when the stream is closed, 
or when a program terminates normally without closing the stream. Also, 
fflush(NULL) flushes all streams opened for output. 


The stream remains open after the call. The fflush function has no effect on an un- 
buffered stream. 


The fflush function returns the value 0 if the buffer was successfully flushed. The 
value 0 is also returned in cases in which the specified stream has no buffer or is 
open for reading only. A return value of EOF indicates an error. 


Note If fflush returns EOF, data may have been lost because of a failed write. 
When setting up a critical error handler, it is safest to turn buffering off with the 
setvbuf function or to use low-level I/O routines such as _ open, —_ close, and 

_ write instead of the stream I/O functions. 


Standards: ANSI, UNIX 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 


fclose, _ flushall, setbuf 
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Example 


Output 


fflush 


/* FFLUSH.C x*/ 
d#Finclude <stdio.h> 
d#FAinclude <conio.h> 


void main( void ) 

{ 
int integer; 
char string[81]; 


/* Read each word as a string. */ 
printf( "Enter a sentence of four words with scanf: " ); 
for( integer = @; integer < 4; integer++ ) 
{ 
scanf( "%s", string ); 
printf( "%s\n", string ); 
} 


/* You must flush the input buffer before using gets. */ 
fflush( stdin ); 

printf( "Enter the same sentence with gets: " ); 

gets( string ); 

printf( "%s\n", string ); 


Enter a sentence of four words with scanf: This is a test 
This 

1S 

a 

test 

Enter the same sentence with gets: This is a test 

This is a test 
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fgetc, _fgetchar 


Description Read a character from a stream (fgetc) or stdin (_ fgetchar). 
#include <stdio.h> 


int fgetc( FILE *stream ); 


int _fgetchar( void ); 
stream Pointer to FILE structure 


Remarks The fgete function reads a single character from the current position of the file as- 
sociated with stream. The character is converted and returned as an int. The func- 
tion then increments the associated file pointer (if any) to point to the next 
character. The _fgetchar function is equivalent to fgetc(stdin). 


The fgetc and _ fgetchar routines are identical to gete and getchar, but they are 
functions rather than macros. 


Return Value The fgete and _fgetchar functions return the character read. They return EOF to 
indicate an error or end-of-file. Use feof or ferror to distinguish between an error 
and an end-of-file condition. 


Compatibility fgetc 
Standards: ANSI, UNIX 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 
_fgetchar 
Standards: None 
16-Bit: DOS, QWIN 
32-Bit: DOS32X 


See Also fputc, _fputchar, getc, getchar 
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Example /* FGETC.C: This program uses getc to read the first 80 input characters 


* (or until the end of input) and place them into a string named buffer. 


d#Hinclude <stdio.h> 
d#FAinclude <stdlib.h> 


void main( void ) 


{ 
FILE *stream; 
char buffer[81]; 
int 7, ch; 
/* Open file to read line from: */ 
if( (stream = fopen( "“fgetc.c", “r”™ )) == NULL ) 
exit( @ ); 
/* Read in first 8@ characters and place them in "buffer": */ 
ch = fgetc( stream ); 
for( i=@; (i < 80 ) && ( feof( stream ) == @ ); i++ ) 
{ 
bufferLi] = ch; 
ch = fgetc( stream ); 
} 
/* Add null to end string */ 
buffer[ i] =. *\e"s 
printf( "%s\n", buffer ); 
fclose( stream ); 
} 


Output /* FGETC.C: This program uses getc to read the first 80 input characters 
/* (or 


Description 


Remarks 


Return Value 


Compatibility 


See Also 
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fgetpos 
Gets a stream’s file-position indicator. 
#include <stdio.h> 
int fgetpos( FILE *stream, fpos_t *pos ); 


stream Target stream 


pos Position-indicator storage 


The fgetpos function gets the current value of the stream argument’s file-position 


indicator and stores it in the object pointed to by pos. The fsetpos function can 
later use information stored in pos to reset the stream argument’s pointer to its 
position at the time fgetpos was called. 


The pos value is stored in an internal format and is intended for use only by the 
fgetpos and fsetpos functions. 


If successful, the fgetpos function returns 0. On failure, it returns a nonzero value 
and sets errno to one of the following manifest constants (defined in STDIO.H): 


Constant Meaning 
EBADF The specified stream is not a valid file handle or is not accessible. 
EINVAL The stream value is invalid. 


Standards: ANSI 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 


fsetpos 


276 ~—s fgetpos 


Example /* FGETPOS.C: This program opens a file and reads bytes at several 
* different locations. 
* / 
d#Finclude <stdio.h> 


void main( void ) 


{ 
FILE *sStream; 
fpos_t pos; 
aa val; 
char buffer[2Q@]; 
if( (stream = fopen( "fgetpos.c", "rb" )) == NULL ) 
printf( "Trouble opening file\n" ); 
else 
{ 
/* Read some data and then check the position. */ 
fread( buffer, sizeof( char ), 10, stream ); 
if( fgetpos( stream, &pos ) != @ ) 
perror( "fgetpos error" ); 
else 
{ 
fread( buffer, sizeof( char ), 10, stream ); 
printf( "10 bytes at byte 41d: %.10s\n", pos, buffer ); 
} 
/* Set a new position and read more data */ 
pos = 14@; 
if( fsetpos( stream, &pos ) != @ ) 
perror( "fsetpos error” ); 
fread( buffer, sizeof( char ), 10, stream ); 
printf( "10 bytes at byte %1ld: %.1@s\n", pos, buffer ); 
fclose( stream ); 
} 
} 
Output 10 bytes at byte 10: .C: This p 


10 bytes at byte 140: FILE * 


Description 


Remarks 


Return Value 


Compatibility 


See Also 
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fgets 
Gets a string from a stream. 


#include <stdio.h> 


char *fgets( char *string, int n, FILE “stream ); 


string Storage location for data 
n Number of characters stored 
stream Pointer to FILE structure 


The fgets function reads a string from the input stream argument and stores it in 
string. Characters are read from the current stream position up to and including the 
first newline character (’\n’), up to the end of the stream, or until the number of 
characters read is equal to n — 1, whichever comes first. The result is stored in 
string, and a null character (’\0’) is appended. The newline character, if read, is in- 
cluded in the string. If n is equal to 1, string is empty ("""). The fgets function is 
similar to the gets function; however, gets replaces the newline character with 
NULL. 


If successful, the fgets function returns string. It returns NULL to indicate either 
an error or end-of-file condition. Use feof or ferror to determine whether an error 
occurred. 


Standards: ANSI, UNIX 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 


fputs, gets, puts 
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Example /* FGETS.C: This program uses fgets to display a line from a file on the 
* screen. 
* / 
fHinclude <stdio.h> 
FILE *stream; 
void main( void ) 
{ 


char lineL100], *result; 


if( (stream = fopen( "fgets.c", "r" )) != NULL ) 


{ 
if( fgets( line, 100, stream ) == NULL) 
printf( "fgets error\n" ); 
else 
printf( "%s", line); 
fclose( stream ); 
i 


} 


Output /* FGETS.C: This program uses fgets to display a line from a file on the 


Description 


Remarks 


Return Value 


Compatibility 


See Also 
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_fieeetomsbin, _fmsbintoieee 


Convert floating-point numbers between IEEE and Microsoft binary formats. 
#include <math.h> 


int _fieeetomsbin( float *s7c4, float *dst4 ); 


int _fmsbintoieee( float *src4, float *dst4 ); 


Scr4 Value to be converted 


dst4 Converted value 


The _fieeetomsbin routine converts a single-precision floating-point number in 
IEEE (institute of Electrical and Electronic Engineers) format to Microsoft (MS) 
binary format. 


The _fmsbintoieee routine converts a floating-point number in Microsoft binary 
format to [EEE format. 


These routines allow C programs (which store floating-point numbers in the IEEE 
format) to use numeric data in random-access data files created with Microsoft 
Basic (which stores floating-point numbers in the Microsoft binary format), and 
vice versa. 


The argument src4 points to the float value to be converted. The result is stored at 
the location given by dst4. 


These routines do not handle IEEE NANs (“not a number’’) and infinities. IEEE 
denormals are treated as 0 in the conversions. 


These functions return O if the conversion is successful and 1 if the conversion 
causes an overflow. 


Standards: None 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 


_dieeetomsbin, _ dmsbintoieee 
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Description 


Remarks 


Return Value 


Compatibility 


See Also 


_filelength 


Gets the length of a file. 
#include <io.h> Required only for function declarations 
long _ filelength( int handle ); 


handle Target file handle 
The _filelength function returns the length, in bytes, of the target file associated 
with handle. 


The _ filelength function returns the file length in bytes. A return value of —1L in- 
dicates an error, and an invalid handle sets errno to EBADF. 


Standards: None 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 


_chsize, _ fileno, _fstat, _ stat 


Example /* CHSIZE.C: This program uses _filelength to report the size of a 


* file 
* / 


before and after modifying it with _chsize. 


#Finclude <io.h> 
#tinclude <fcntl.h> 
#Hinclude <sys\types.h> 
#include <sys\stat.h> 
#Hinclude <stdio.h> 
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void main( void ) 


{ 
int fh, result; 
unsigned int nbytes = BUFSIZ; 
/* Open a file */ 
if( (fh = _open( "data", _O_RDWR | _O_CREAT, 
_S_IREAD | _S_IWRITE )) != -1 ) 
{ 
printf( "File length before: 41d\n", _filelength( fh ) ); 
if( _chsize( fh, 329678 ) == @ ) 
printf( "Size successfully changed\n" ); 
else 
printf( "Problem in changing the size\n" ); 
printf( "File length after: %1d\n", _filelength( fh ) ); 
_close( fh ); 
} 
} 
Output File length before: @ 


Size successfully changed 
File length after: 329678 
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Description 


Remarks 


Return Value 


Compatibility 


See Also 


_fileno 


Gets the file handle associated with a stream. 
#include <stdio.h> 


int _ fileno( FILE *stream ); 


stream Pointer to FILE structure 


The _fileno routine returns the file handle currently associated with stream. This 
routine is implemented both as a function and as a macro. 


The _fileno routine returns the file handle. There is no error return. The result 1s 
undefined if stream does not specify an open file. 


Standards: UNIX 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 


Use _fileno for compatibility with ANSI naming conventions of non-ANSI func- 
tions. Use fileno and link with OLDNAMES.LIB for UNIX compatibility. 


_fdopen, _filelength, fopen, freopen 


Example /* FILENO.C: This program uses _fileno to obtain the file handle for 
* some standard C streams. 


*/ 


d#Finclude <stdio.h> 


void main( void ) 


{ 
printf( "The file handle for stdin is %d\n", _fileno( stdin ) ); 
printf( "The file handle for stdout is 4d\n", _fileno( stdout ) ); 
printf( "The file handle for stderr is 4d\n", _fileno( stderr ) ); 
} 
Output The file handle for stdin is Q 


The file handle for stdout is 1 
The file handle for stderr is 2 


Description 


Remarks 


Return Value 


Compatibility 


See Also 
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_floodfill, — floodfill_w 
Fill an area of a display using the current color and fill mask. 
#include <graph.h> 


short __ far _ floodfill( short x, short y, short boundary ); 


short __ far _ floodfill_w( double wx, double wy, short boundary ); 


x,y Start point 
Wx, Wy Start point 
boundary Boundary color of area to be filled 


The functions in the _ floodfill family fill an area of the display, using the current 
color and fill mask. The _ floodfill routine begins filling at the view-coordinate 
point (x, y). The _ floodfill_ w routine begins filling at the window-coordinate 
point (wx, wy). 


If this point lies inside the figure, the interior is filled; if it lies outside the figure, 
the background is filled. The point must be inside or outside the figure to be filled, 
not on the figure boundary itself. Filling occurs in all directions, stopping at the 
color of boundary. 


The _ floodfill functions return a nonzero value if the fill is successful. They return 
O if the fill could not be completed, the starting point lies on the boundary color, or 
the start point lies outside the clipping region. 


Standards: None 
16-Bit: DOS 
32-Bit: None 


_ ellipse functions, _ getcolor, _ getfillmask, _grstatus, _ pie functions, 
_Setfillmask, _setcliprgn, —setcolor 
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Example /* FLOODFIL.C: This program draws a series of nested rectangles in 
* different colors, constantly changing the background color. 
* / 


#Finclude <conio.h> 
d#Finclude <stdlib.h> 
#Hinclude <graph.h> 


void main( void ) 
{ 

int loop; 

int xvar, yvar; 


/* find a valid graphics mode */ 
if( !_setvideomode( _MAXCOLORMODE ) ) 
exec as 


for( xvar = 163, loop = @; xvar < 320; loopt+, xvar += 3 ) 
{ 
_setcolor( loop % 16 ); 
yvar = xvar * 5 / 8; 
_rectangle( _GBORDER, 320-xvar, 200-yvar, xvar, yvar ); 
_setcolor( rand() % 16 ); 
_floodfill( @, @, loop % 16 ); 
} 
_getch(); 
_setvideomode( _DEFAULTMODE ); 
} 


Description 


Remarks 


Return Value 


Compatibility 


See Also 
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floor, _ floor! 


Calculate the floor of a value. 


#include <math.h> 


double floor( double x ); 


long double _floorl( long double x ); 


Floating-point value 


The floor and _floorl functions return a floating-point value representing the 
largest integer that is less than or equal to x. 


The _ floorl function is the 80-bit counterpart, and it uses the 80-bit, 10-byte co- 
processor form of arguments and return values. See the reference page on the long 
double functions for more details on this data type. 


These functions return the floating-point result. There is no error return. 


floor 
Standards: 
16-Bit: 
32-Bit: 


_floorl 
Standards: 
16-Bit: 
32-Bit: 


ceil, fmod 


ANSI, UNIX 
DOS, QWIN, WIN, WIN DLL 
DOS32X 


None 
DOS, QWIN, WIN, WIN DLL 


None 
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Example /* FLOOR.C: This example displays the largest integers less than or equal 
* to the floating-point values 2.8 and -2.8. It then shows the smallest 
* integers greater than or equal to 2.8 and -2.8. 
* / ; 


d#Ainclude <math.h> 
d#Ainclude <stdio.h> 


void main( void ) 
{ 
double y; 


y = floor( 2.8 ); 

printf( "The floor of 2.8 is “f\n", y ); 
y= Tloor(.=2.8 5 

printf( "The floor of -2.8 is %f\n", y ); 


y = ceil( 2.8 ); 

printf( "The ceil of 2.8 is 4f\n", y ); 
y = cerlt -2.8 ); 

printf( "The ceil of -2.8 is 4f\n", y ); 


Output The floor of 2.8 is 2.000000 
The floor of -2.8 is -3.000000 
The ceil of 2.8 is 3.000000 
The ceil of -2.8 is -2.000000 
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_ flushall 


Description Flushes all streams; clears all buffers. 
#include <stdio.h> 


int _ flushall( void ); 


Remarks The _ flushall function writes to its associated files the contents of all buffers as- 
sociated with open output streams. All buffers associated with open input streams 
are Cleared of their current contents. The next read operation (if there is one) then 
reads new data from the input files into the buffers. 


Buffers are automatically flushed when they are full, when streams are closed, or 
when a program terminates normally without closing streams. 


All streams remain open after the call to _ flushall. 


Return Value The _ flushall function returns the number of open streams (input and output). 
There is no error return. 


Compatibility Standards: None 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 

See Also fflush 


Example /* FLUSHALL.C: This program uses _flushall to flush all open buffers. */ 
dFinclude <stdio.h> 


void main( void ) 


‘ 

int numflushed; 

numflushed = _flushal1(); 

printf( “There were %d streams flushed\n", numflushed ); 
i 


Output There were 3 streams flushed 
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Description 


Remarks 


Return Value 


Compatibility 


See Also 


fmod, _ fmodl 


Calculate the floating-point remainder. 
#include <math.h> 


double fmod( double x, double y ); 


long double _fmodl( long double x, long double y ); 


x,y Floating-point values 


The fmod and _fmodI functions calculate the floating-point remainder f of x / y 
such that x =i * y +f, where iis an integer, f has the same sign as x, and the abso- 
lute value of f is less than the absolute value of y. 


The _fmodI function is the 80-bit counterpart; it uses the 80-bit, 10-byte coproces- 
sor form of arguments and return values. See the discussion of the long double 
functions for more details on this data type. 


These functions return the floating-point remainder. If y is 0, the function returns 0. 


fmod 

Standards: ANSI, UNIX 

16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 

_fmodl 

Standards: None 

16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: None 


ceil, fabs, floor 


Example 


Output 


fmod, _fmodl 


/* FMOD.C: This program displays a floating-point remainder. */ 


dEinclude <math.h> 
dFinclude <stdio.h> 


void main( void ) 


{ 

double x = -10.0, y = 3.0, Zz; 

z = fmod( x, y ); 

printf( "The remainder of %.2f / %.2f is “4f\n", x, y, z ); 
} 


The remainder of -10.0@ / 3.00 is -1.000000 
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Description 


Remarks 


fopen 


Opens a file. 
#include <stdio.h> 
FILE *fopen( const char *filename, const char *mode ); 


filename Path name of file 


mode Type of access permitted 


The fopen function opens the file specified by filename. The character string mode 
specifies the type of access requested for the file, as follows: 


Type Description 


r Opens for reading. If the file does not exist or cannot be found, the 
fopen call will fail. 


w Opens an empty file for writing. If the given file exists, its contents 

are destroyed. 

"a! Opens for writing at the end of the file (appending); creates the file 
first if it doesn’t exist. 

co Opens for both reading and writing. (The file must exist.) 

w+" Opens an empty file for both reading and writing. If the given file 
exists, its contents are destroyed. 

"at" Opens for reading and appending; creates the file first if it doesn’t 


exist. 


When a file is opened with the ''a" or "a+" access type, all write operations occur 
at the end of the file. Although the file pointer can be repositioned using fseek or 
rewind, the file pointer is always moved back to the end of the file before any 
write operation is carried out: Thus, existing data cannot be overwritten. 


When the "r+", ''w+"', or ''a+"' access type is specified, both reading and writing 
are allowed (the file is said to be open for “update’”). However, when you switch 
between reading and writing, there must be an intervening fsetpos, fseek, or 
rewind operation. The current position can be specified for the fsetpos or fseek 
operation, if desired. 


Return Value 


Compatibility 


See Also 
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In addition to the values listed above, the following characters can be included in 
mode to specify the translation mode for newline characters: 


Mode Meaning 


t Open in text (translated) mode. In this mode, carriage-return—line- 
feed (CR-LF) combinations are translated into single line feeds (LF) 
on input and LF characters are translated to CR-LF combinations on 
output. Also, CTRL+Z is interpreted as an end-of-file character on 
input. In files opened for reading or for reading/writing, fopen checks 
for a CTRL+Z at the end of the file and removes it, if possible. This is 
done because using the fseek and ftell functions to move within a file 
that ends with a CTRL+Z may cause fseek to behave improperly near 


the end of the file. 

b Open in binary (untranslated) mode; the above translations are 
suppressed. 

c Enable the commit flag for the associated filename so that the 


contents of the file buffer are written directly to disk if either fflush 
or _ flushall is called. 


n Reset the commit flag for the associated filename to “no-commit”. 
This is the default. It will also override the global commit flag if you 
have linked your program with COMMODE.OBJ. The global 
commit flag default is “no-commit” unless you explicitly link your 
program with COMMODE.OBJ. 


If t or b is not given in mode, the translation mode is defined by the default-mode 
variable _fmode. If t or b is prefixed to the argument, the function will fail and re- 
turn NULL. 


For a discussion of text and binary modes see “Input and Output” on page 31. 


The fopen function returns a pointer to the open file. A null pointer value indicates 
an error. 


Standards: ANSI, UNIX 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 


Note that the c, n, and t options are not part of the ANSI standard for fopen; they 
are Microsoft extensions and should not be used where ANSI portability is desired. 


f{close, _fcloseall, _fdopen, ferror, _ fileno, freopen, _ open, _setmode 
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Example /* FOPEN.C: This program opens files named "data" and "data2". It uses 
* fclose to _close "data" and _fcloseall to close all remaining files. 
* / 


#tinclude <stdio.h> 
FILE «stream, *stream2; 


void main( void ) 
{ 
int numclosed; 


/* Open for read (will fail if ‘data’ does not exist) */ 
if( (stream = fopen( "data", "r" )) == NULL ) 

printf( "The file "data' was not opened\n"™ ); 
else 

printf( "The file ‘data’ was opened\n" ); 


/* Open for write */ 
if( (stream2 = fopen( "data2", "wt" )) == NULL ) 
printf( "The file 'data2' was not opened\n" ); 
else 
printf( "The file ‘data2' was opened\n" ); 


/* Close stream */ 
if( fclose( stream ) ) 
printf( "The file 'data' was not closed\n" ); 


/* All other files are closed: */ 


numclosed = _fcloseall( ); 
printf( "Number of files closed by _fcloseall: %“4u\n", numclosed ); 
} 
Output The file ‘data’ was opened 


The file ‘data2' was opened 
Number of files closed by _fcloseall: 1 


Description 
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_FP_OFF, _FP_SEG 
Get or set a far-pointer offset (_FP_ OFF) or a far-pointer segment (_ FP_SEG). 
#include <dos.h> 


unsigned _ FP_OFF‘( void __ far “address ); 
unsigned _ FP_SEG( void __ far “address ); 


address Far pointer to memory address 


Remarks The _FP_OFF and _FP_SEG macros can be used to set or get the offset and seg- 
ment, respectively, of the far pointer at address. 

Return Value The _FP_OFF macro returns an offset. The _FP_SEG macro returns a segment 
address. 

Compatibility Standards: None 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: None 

Example /* _FP_SEG.C: This program uses _FP_SEG and _FP_OFF to obtain 


* the segment and offset of the long pointer p. 
* / 


dEinclude <dos.h> 
d#Finclude <malloc.h> 
d#Hinclude <stdio.h> 


void main( void ) 

{ 
void __far *p; 
unsigned int seg_val; 


—- unsigned int off_val; 


p = _fmalloc( 10@ ); /* Points pointer at something */ 
seg_val = _FP_SEG( p ); /* Gets address pointed to */ 
off_val = _FP_OFF( p ); 


printf( "Segment is %.4X; Offset is %.4X\n", seg_val, off_val ); 
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Output Segment is QQC7; Offset is 0016 


Description 


Remarks 


Return Value 


Compatibility 


See Also 
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_ fpreset 


Resets the floating-point package. 
#include <float.h> 


void _ fpreset( void ); 


The _fpreset function reinitializes the floating-point-math package. This function 
is usually used in conjunction with signal, system, or the _ exec or _spawn 
functions. 


If a program traps floating-point error signals (SIGFPE) with signal, it can safely 
recover from floating-point errors by invoking _ fpreset and using longjmp. 


In DOS versions prior to 3.0, a child process executed by _ exec, _ spawn, or 
system may affect the floating-point state of the parent process if an 8087, 80287, 
or 80387 coprocessor is used. If you are using either coprocessor, the following 
precautions are recommended: 


= The _exec, _spawn, and system functions should not be called during the eval- 
uation of a floating-point expression. 


= The _fpreset function should be called after these routines if there is a possi- 
bility of the child process performing any floating-point operations. 


None. 


Standards: None 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 


_exec functions, signal, _ spawn functions 
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Example /* FPRESET.C: This program uses signal to set up a routine for handling 


* floating-point errors. 


#Hinclude <stdio.h> 
#Finclude <signal.h> 
#Hinclude <setjmp.h> 
#Finclude <stdlib.h> 
#include <float.h> 
#Hinclude <math.h> 

#Hinclude <string.h> 


jmp_buf mark; /* Address for long jump to jump to */ 


int 


fperr; /* Global error number */ 


void fphandler( int sig, int num ); /* Prototypes */ 
void fpcheck( void ); | 


void main( void ) 


{ 


double nl, n2, r; 
int jmpret; 


/* Set up floating-point error handler. The compiler 

* will generate a warning because it expects 

* Signal-handling functions to take only one argument. 

* / 

if( signal( SIGFPE, fphandler ) == SIG_ERR ) 

{ 
fprintf( stderr, "Couldn't set SIGFPE\n" ); 
abort(); 

} 


/* Save stack environment for return in case of error. First time 
* through, jmpret is @, so true conditional is executed. If an 
* error occurs, jmpret will be set to -1 and false conditional 
* will be executed. 

* / 

jmpret = setjmp( mark ); 

if( jmpret == @ ) 

{ 

printf( "Test for invalid operation - " ); 
printf( "enter two numbers: " ); 
scanf( "%1f “1f", &nl, &n2 ); 


Rend .£.inZzs 
/* This won't be reached if error occurs. */ 
printf( "\n\n%4.3g / %44.3g = %44.3g\n", nl, n2, r ); 


_ fpreset 


r=nl * n2; 
/* This won't be reached if error occurs. */ 
printf( "\n\n%Z4.3g * 44.39 = %44.3g\n", nl, n2, r ); 


} 
else 
fpcheck(); 

} 

/* fphandler handles SIGFPE (floating-point error) interrupt. Note 
* that this prototype accepts two arguments and that the prototype 
* for signal in the run-time library expects a signal handler to 
* have only one argument. 

* 
* The second argument in this signal handler allows processing of 
* _FPE_INVALID, _FPE_OVERFLOW, _FPE_UNDERFLOW, and _FPE_ZERODIVIDE 
* all of which are Microsoft-specific symbols that augment the 
* information provided by SIGFPE. The compiler will generate a 
* warning, which is harmless and expected. 
* / 
void fphandler( int sig, int num ) 
{ 
/* Set global for outside check since we don't want 
* to do I/0 in the handler. 
* / 
fperr = num; 
/* Initialize floating-point package. */ 
_fpreset(); 
/* Restore calling environment and jump back to setjmp. Return -1 
* So that setjmp will return false for conditional test. 
* / 
longjmp( mark, -1 ); 
} 


void fpcheck( void ) 
{ 
char fpstr[l30]; 


Switch( fperr ) 
{ 
case _FPE_INVALID: 


strcpy( fpstr, "Invalid number" ); 
break; 


case _FPE_OVERFLOW: 
strcpy( fpstr, "Overflow" ); 
break; 


case _FPE_UNDERFLOW: 
Strcpy( fpstr, "Underflow"™ ); 
break; 
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Output 
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case _FPE_ZERODIVIDE: 
strcpy( fpstr, "Divide by zero" ); 
break; 


default: 
strcepy( fpstr, "Other floating point error" 
break; 
i 
printf( "Error 4d: %s\n", fperr, fpstr ); 


Test for invalid operation - enter two numbers: 5 @ 
Error 131: Divide by zero 


Description 


Remarks 


Return Value 


Compatibility 


See Also 
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fprintt 
Prints formatted data to a stream. 


#include <stdio.h> 


int fprintf( FILE *stream, const char *format [| , argument |... )5 


stream Pointer to FILE structure 
format Format-control string 
argument Optional arguments 


The fprintf function formats and prints a series of characters and values to the out- 
put stream. Each argument (if any) is converted and output according to the corre- 
sponding format specification in format. 


The format argument has the same form and function that it does for the printf 
function; see the Remarks section for the printf function for more information on 
format and argument. 


The fprintf function returns the number of characters printed, or a negative value 
in the case of an output error. 


Standards: ANSI, UNIX 
16-Bit: DOS, QWIN, WIN 
32-Bit: DOS32X 


_cprintf, fscanf, printf, sprintf 


300 fprintf 


Example /* FPRINTF.C: This program uses fprintf to format various data and 
* print them to the file named FPRINTF.OUT. It then displays 

FPRINTF.OUT on the screen using the system function to invoke 

* the DOS TYPE command. 

a / 


% 


d#Finclude <stdio.h> 
#tinclude <process.h> 


FILE *stream; 


void main( void ) 


{ 
int j = 10; 
double fp = 1.5; 
char SL] = "this is a string"; 
char c= "An's 
stream = fopen( "fprintf.out", "w" ); 
fprintf( stream, "%s%c", Ss, Cc ); 
fprintf( stream, "%d\n", i ); 
fprintf( stream, "%f\n", fp ); 
fclose( stream ); 
system( "type fprintf.out" ); 

} 

Output this is a string 
10 
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Description 


Remarks 


Return Value 


Compatibility 


See Also 
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foutc, _ fputchar 


Write a character to a stream (fputc) or to stdout (_fputchar). 
#include <stdio.h> 


int fputc( int c, FILE *stream ); 


int _fputchar( int c ); 


C Character to be written 


stream Pointer to FILE structure 


The fpute function writes the single character c to the output stream at the current 
position. The _ fputchar function is equivalent to fputc(c, stdout). 


The fpute and _ fputchar routines are similar to pute and putchar, but are func- 
tions rather than macros. 


The fpute and _fputchar functions return the character written. A return value of 
EOF indicates an error. 


{fputc 

Standards: ANSI, UNIX 

16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 

_fputchar 

Standards: None 

16-Bit: DOS, QWIN 

32-Bit: DOS32X 


fgetc, _fgetchar, putc, putchar 
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Example /* FPUTC.C: This program uses fputc and _fputchar to send a character 
* array to stdout. 
* / 
#Hinclude <stdio.h> 


void main( void ) 


{ 
char strptr1[L] = "This is a test of fputc!!\n"; 
char strptr2[] = "This is a test of _fputchar!!\n"; 
char *p; 
/* Print line to stream using fputc. */ 
Dp = Sstrptrl; 
while( (*p != "\@') && fputc( *(ptt+), stdout ) != EOF ) 
/* Print line to stream using _fputchar. */ 
p = strptr2; 
while( (*p != '\@") && _fputchar( *(p++) ) != EOF ) 

} 

Output This is a test of fputc!! 


This is a test of _fputchar!! 
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fputs 
Description Writes a string to a stream. 


#include <stdio.h> 


int fputs( const char “string, FILE *stream ); 


string String to be output 
stream Pointer to FILE structure 
Remarks The fputs function copies string to the output stream at the current position. The 


terminating null character (’\0’) is not copied. 


Return Value The fputs function returns a nonnegative value if it is successful. If an error oc- 
curs, it returns EOF. 


Compatibility Standards: ANSI, UNIX 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 

See Also fgets, gets, puts 


Example /* FPUTS.C: This program uses fputs to write a single line to the 
* Stdout stream. 
x / 


dAinclude <stdio.h> 
void main( void ) 
{ 


fputs( "Hello world from fputs.\n", stdout ); 
I 


Output Hello world from fputs. 
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Description 


Remarks 


Return Value 


Compatibility 


See Also 


fread 


Reads data from a stream. 
#include <stdio.h> 


size_t fread( void *buffer, size_t size, size_t count, FILE *stream ); 


buffer Storage location for data 

size Item size in bytes 

count Maximum number of items to be read 
stream Pointer to FILE structure 


The fread function reads up to count items of size bytes from the input stream and 
stores them in buffer. The file pointer associated with stream (if there is one) is in- 
creased by the number of bytes actually read. 


If the given stream is opened in text mode, carriage-return—line-feed pairs are re- 
placed with single line-feed characters. The replacement has no effect on the file 
pointer or the return value. 


The file-pointer position is indeterminate if an error occurs. The value of a par- 
tially read item cannot be determined. 


The fread function returns the number of full items actually read, which may be 
less than count if an error occurs or if the file end is encountered before reaching 
count. 


The feof or ferror function should be used to distinguish a read error from an end- 
of-file condition. If size or count is O, fread returns 0 and the buffer contents are 
unchanged. 


Standards: ANSI, UNIX 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 


fwrite, _read 


Example 


Output 


/ 


* 
*K 
* 
* 


* / 


fread 


FREAD.C: This program opens a file named FREAD.OUT and writes 25 
Characters to the file. It then tries to open FREAD.OUT and 

read in 25 characters. If the attempt succeeds, the program 
displays the number of actual items read. 


dFinclude <stdio.h> 


void main( void ) 


{ 


FILE *stream; 
char list[3@]; 
int 71, numread, numwritten; 


/* Open file in text mode: */ 
if( (stream = fopen( "fread.out", "w+t" )) != NULL ) 
{ 
FO ES Oe FD KR 25 ae) 
listLi] = 'z' - i: 
/* Write 25 characters to stream */ 
numwritten = fwrite( list, sizeof( char ), 25, stream ); 
printf( "Wrote %d items\n", numwritten ); 
fclose( stream ); 
J 
else 
printf( "Problem opening the file\n" ); 


if( (stream = fopen( "fread.out", "r+t" )) != NULL ) 

{ 
/* Attempt to read in 25 characters */ 
numread = fread( list, sizeof( char ), 25, stream ); 
printf( "Number of items read = %d\n", numread ); 
printf( "Contents of buffer = %.25s\n", list ); 
fclose( stream ); 

} 

else 
printf( "Was not able to open the file\n" ); 


Wrote 25 items 
Number of items read = 25 
Contents of buffer = zyxwvutsrqponmlkjihgfedcb 
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free Functions 


Description Deallocate a memory block. 
#include <stdlib.h> For ANSI compatibility (free only) 
#include <malloc.h> Required only for function declarations 


void free( void *memblock ); 
void _bfree( __segment seg, void __based( void ) *memblock ); 
void _ ffree( void __far *memblock ); 


void _nfree( void __ near *memblock ); 


memblock Allocated memory block 
seg Based-heap segment selector 
Remarks The free family of functions deallocates a memory block. The argument 


memblock points to a memory block previously allocated through a call to calloc, 
malloc, or realloc. The number of bytes freed is the number of bytes specified 
when the block was allocated (or reallocated, in the case of realloc). After the call, 
the freed block is available for allocation. 


The seg argument specifies the based heap containing the memory block to be 
freed by the _ bfree function. 


Attempting to free an invalid pointer may affect subsequent allocation and cause 
errors. An invalid pointer is one not allocated with the appropriate call. 


The following restrictions apply to use of the free, _ bfree, _ ffree, and _nfree 


functions: 

Blocks allocated with: Should be freed with: 
calloc, malloc, realloc free 

_bealloc, _bmalloc, _ brealloc _bfree 

_fcalloc, _fmalloc, _ frealloc _ffree 


_necalloc, _nmalloc, — nrealloc _nfree 


free Functions 307 


A NULL pointer argument is ignored. 


In large data models (compact-, large-, and huge-model programs), free maps to 
_ffree. In small data models (tiny-, small-, and medium-model programs), free 
maps to _nfree. 


The various free functions deallocate a memory block in the segments shown in 


the list below: 
Function Data Segment 
free Depends on data model of program 
_bfree Based heap specified by seg value 
_ffree Far heap (outside default data segment) 
_nfree Near heap (inside default data segment) 
Return Value None. 
Compatibility free 
Standards: ANSI, UNIX 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 


_bfree, _ ffree, _ nfree 


Standards: None 


16-Bit: DOS, WIN, WIN DLL 
32-Bit: None 
See Also calloc functions, malloc functions, realloc functions 


Example /* MALLOC.C: This program allocates memory with malloc, then frees 
* the memory with free. 
* / 


d#Hinclude <stdlib.h> /* Definition of _MAX_ PATH */ 
dinclude <stdio.h> 
4#Hinclude <malloc.h> 
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void main( void ) 


{ 
char *string; 
/* Allocate space for a path name */ 
string = malloc( _MAX_PATH ); 
if( string == NULL ) 
printf( “Insufficient memory available\n" ); 
else 
printf( "Memory space allocated for path name\n" ); 
free( string ); 
printf( "Memory freed\n" ); 
J 
Output Memory space allocated for path name 


Memory freed 
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_ freect 


Description Returns the amount of memory available for memory allocation. 
#include <malloc.h> Required only for function declarations 
unsigned int _ freect( size_t size ); 


size Item size in bytes 


Remarks The _freect function tells you how much memory is available for dynamic 
memory allocation in the near heap. It does so by returning the approximate num- 
ber of times your program can call _nmalloc (or malloc in small data models) to 
allocate an item size bytes long in the near heap (default data segment). 


Return Value The _ freect function returns the number of calls as an unsigned integer. 
Compatibility Standards: None 

16-Bit: DOS, QWIN, WIN, WIN DLL 

32-Bit: None 
See Also calloc functions, _ expand functions, malloc functions, _memavl, _ msize func- 


tions, realloc functions 


Example /* FREECT.C: This program determines how much free space is available for 
* integers in the default data segment. Then it allocates space for 
* 1,000 integers and checks the space again, using _freect. 
* / 


d4Einclude <malloc.h> 
dEinclude <stdio.h> 
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void main( void ) 
{ 


TAG 1 


/* First report on the free space: */ 
printf( "Integers (approximate) available on heap: %u\n\n", 
_freect( sizeof( int ) ) ); 


/* Allocate space for 1000 integers: */ 
for( i = @; i < 1000; ++i ) 
malloc( sizeof( int ) ); 


/* Report again on the free space: */ 

printf( "After allocating space for 1000 integers:\n" ); 

printf( "Integers (approximate) available on heap: Z%u\n\n", 
_freect( sizeof( int ) ) ); 


Output Integers (approximate) available on heap: 15212 


After allocating space for 1000 integers: 
Integers (approximate) available on heap: 14084 


Description 


Remarks 
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freopen 


Reassigns a file pointer. 
#include <stdio.h> 


FILE *freopen( const char “filename, const char *mode, FILE *stream ); 


filename Path name of new file 
mode Type of access permitted 
stream Pointer to FILE structure 


The freopen function closes the file currently associated with stream and reas- 
signs stream to the file specified by filename. The freopen function is typically 
used to redirect the pre-opened files stdin, stdout, and stderr to files specified by 
the user. The new file associated with stream is opened with mode, which is a char- 
acter string specifying the type of access requested for the file, as follows: 


Type Description 


r Opens for reading. If the file does not exist or cannot be found, the 
freopen call fails. 


"w"! Opens an empty file for writing. If the given file exists, its contents are 
destroyed. 

"a" Opens for writing at the end of the file (appending); creates the file first 
if it does not exist. 

"r+" Opens for both reading and writing. (The file must exist.) 

"w+" Opens an empty file for both reading and writing. If the given file exists, 
its contents are destroyed. 

"a+" Opens for reading and appending; creates the file first if it does not exist. 


Use the ''w"' and "w+"' types with care, as they can destroy existing files. 


roe 


When a file is opened with the ''a" or ''a+'' access type, all write operations take 
place at the end of the file. Although the file pointer can be repositioned using 
fseek or rewind, the file pointer is always moved back to the end of the file before 
any write operation is carried out. Thus, existing data cannot be overwritten. 
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Return Value 


Compatibility 


See Also 


When the "r+", ''w+"', or ''at+'' access type is specified, both reading and writing 
are allowed (the file is said to be open for “update’’). However, when you switch 
between reading and writing, there must be an intervening fsetpos, fseek, or 
rewind operation. The current position can be specified for the fsetpos or fseek 
operation, if desired. , 


In addition to the values listed above, one of the following characters may be in- 
cluded in the mode string to specify the translation mode for new lines. 


Mode Meaning 


t Open in text (translated) mode; carriage-return—line-feed 
(CR-LF) combinations are translated into single line-feed (LF) 
characters on input; LF characters are translated to CR-LF combinations 
on output. Also, CTRL+Z is interpreted as an end-of-file character on 
input. In files opened for reading, or writing and reading, the run-time 
library checks for a CTRL+Z at the end of the file and removes it, if 
possible. This is done because using the fseek and ftell functions to 
move within a file may cause fseek to behave improperly near the end 
of the file. 


b Open in binary (untranslated) mode; the above translations are 
suppressed. 


If t or b is not given in the mode string, the translation mode is defined by the de- 
fault mode variable _fmode. 


See “Input and Output” on page 31 for a discussion of text and binary modes. 


The freopen function returns a pointer to the newly opened file. If an error occurs, 
the original file is closed and the function returns a NULL pointer value. 


Standards: ANSI, UNIX 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 


The t option is not part of the ANSI standard for freopen; it is a Microsoft exten- 
sion that should not be used where ANSI portability is desired. 


fclose, _ fcloseall, _ fdopen, _ fileno, fopen, _ open, _ setmode 
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Example /* FREOPEN.C: This program reassigns stdaux to the file 
* named FREOPEN.OUT and writes a line to that file. 
* / 


4Ainclude <stdio.h> 
#Hinclude <stdlib.h> 


FILE *stream; 


void main( void ) 


{ 
/* Reassign "stdaux" to "freopen.out": */ 
Stream = freopen( "freopen.out", "w", stdaux ); 
if( stream == NULL ) 
fprintf( stdout, “error on freopen\n" ); 
else 
{ 
fprintf( stream, “This will go to the file 'freopen.out'\n" ); 
fprintf( stdout, “successfully reassigned\n" ); 
fclose( stream ); 
} 
system( "type freopen.out" ); 
} 
Output successfully reassigned 


This will go to the file ‘freopen.out' 
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Description 


Remarks 


Return Value 


Compatibility 


See Also 


frexp, _ frexpl 


Get the mantissa and exponent of a floating-point number. 
#include <math.h> 


double frexp( double x, int *expptr ); 


long double _ frexpl( long double x, int *expptr ); 


x Floating-point value 


expptr Pointer to stored integer exponent 


The frexp and _frexpl functions break down the floating-point value (x) into a 
mantissa (m) and an exponent (n), such that the absolute value of m is greater than 
or equal to 0.5 and less than 1.0, and x = m*2". The integer exponent n is stored at 
the location pointed to by expptr. 


The _ frexpl function is the 80-bit counterpart and uses an 80-bit, 10-byte co- 
processor form of arguments and return values. See the reference page on the long 
double functions for more details on this data type. 


These functions return the mantissa. If x is 0, the function returns O for both the 
mantissa and the exponent. There is no error return. 


frexp 

Standards: ANSI, UNIX 

16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 

_frexpl 

Standards: None 

16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: None 


Idexp functions, modf 
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Example /* FREXP.C: This program calculates frexp( 16.4, &n ), then displays y 
* and n. 
* / 


deinclude <math.h> 
d4Ainclude <stdio.h> 


void main( void ) 


{ 

double x, y; 

int n; 

xX = 16.4; 

y = frexp( x, &n ); 

printf( "frexp( “4f, &n ) = 4f, n = d\n", x, y, n ); 
} 


Output frexp( 16.400000, &n ) = 0.512500, n = 5 


316 fscanf 


Description 


Remarks 


Return Value 


Compatibility 


See Also 


fscanf 


Reads formatted data from a stream. 
#include <stdio.h> 


int fscanf( FILE *stream, const char “format |[, argument |]... )3 


stream Pointer to FILE structure 
format Format-control string 
argument Optional arguments 


The fscanf function reads data from the current position of stream into the loca- 
tions given by argument (if any). Each argument must be a pointer to a variable 
with a type that corresponds to a type specifier in format. The format controls the 
interpretation of the input fields and has the same form and function as the format 
argument for the scanf function; see scanf for a description of format. 


The fscanf function returns the number of fields that were successfully converted 
and assigned. The return value does not include fields that were read but not 
assigned. 


The return value is EOF for an error or end-of-file on stream before the first con- 
version. A return value of 0 means that no fields were assigned. 


Standards: ANSI, UNIX 
16-Bit: DOS, QWIN, WIN 
32-Bit: DOS32X 


_escanf, fprintf, scanf, sscanf 


Example 


Output 


fscanf 


/* FSCANF.C: This program writes formatted data to a file. It 
* then uses fscanf to read the various data back from the file. 


* / 


dEinclude <stdio.h> 


FILE *stream; 


void main( void ) 


{ 
long 1; 
float fp; 
char s[81]; 
char Cc; 
int result; 
Stream = fopen( "fscanf.out", "wt" ); 
if( stream == NULL ) 
printf( "The file fscanf.out was not opened\n" ); 
else 
{ 
fprintf( stream, "%s 41d %f%c", “a-string", 65000, 3.14159, ‘x' ); 
/* Set pointer to beginning of file: */ 
fseek( stream, @L, SEEK_SET ); 
/* Read data back from file: */ 
fscanf( stream, "%s", S ); 
fscanf( stream, "%1ld", &l ); 
fscanf( stream, "%f", &fp ); 
fscanf( stream, "%c", &c ); 
/* Output data read: */ 
printf( "%s\n", s ); 
DriInthC.“-2ldyn,. 1.) 
printf( "%f\n", fp ); 
printt( ““ze\n". Cc); 
fclose( stream ); 
} 
} 
a-string 
65000 
3.141590 


X 
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fseek 

Description Moves the file pointer to a specified location. 
#include <stdio.h> 


int fseek( FILE *stream, long offset, int origin ); 


stream Pointer to FILE structure 
offset Number of bytes from origin 
origin Initial position 
Remarks The fseek function moves the file pointer (if any) associated with stream to a new 


location that is offset bytes from origin. The next operation on the stream takes 
place at the new location. On a stream open for update, the next operation can be 
either a read or a write. 


The argument origin must be one of the following constants defined in STDIO.H: 


Origin Definition 

SEEK_CUR Current position of file pointer 
SEEK_END End of file 

SEEK_SET Beginning of file 


The fseek function can be used to reposition the pointer anywhere in a file. The 
pointer can also be positioned beyond the end of the file. However, an attempt to 
position the pointer in front of the beginning of the file causes an error. 


The fseek function clears the end-of-file indicator and negates the effect of any 
prior ungetc calls against stream. 


When a file is opened for appending data, the current file position is determined 
by the last I/O operation, not by where the next write would occur. If no I/O opera- 
tion has yet occurred on a file opened for appending, the file position is the start of 
the file. 
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For streams opened in text mode, fseek has limited use because carriage-return— 
line-feed translations can cause fseek to produce unexpected results. The only 
fseek operations guaranteed to work on streams opened in text mode are 


# Seeking with an offset of 0 relative to any of the origin values 


= Seeking from the beginning of the file with an offset value returned from a call 


to ftell 
Return Value If successful, fseek returns 0. Otherwise, it returns a nonzero value. On devices in- 
capable of seeking, the return value is undefined. 
Compatibility Standards: ANSI, UNIX 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 
See Also ftell, _lseek, rewind 
Example /* FSEEK.C: This program opens the file FSEEK.OUT and 


* moves the pointer to the file's beginning. 
* / 
#Hinclude <stdio.h> 


void main( void ) 
{ 
FILE *stream; 
char line[81]; 
int result; 


stream = fopen( "fseek.out", "wt" ); 
if( stream == NULL ) 
printf( "The file fseek.out was not opened\n" ); 
else 
{ 
fprintf( stream, "The fseek begins here: ™ 
"This is the file 'fseek.out'.\n" ); 
result = fseek( stream, 23L, SEEK_SET); 
if( result ) 
perror( "Fseek failed" ); 
else 
{ 
printf( "File pointer is set to middle of first line.\n" ); 
fgets( line, 80, stream ); 
printf( "%s", line ); 
} 
fclose( stream ); 
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Output File pointer is set to middle of first line. 
This is the file 'fseek.out'. 


Description 


Remarks 


Return Value 


Compatibility 


See Also 
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fsetpos 


Sets the stream-position indicator. 
#include <stdio.h> 
int fsetpos( FILE *stream, const fpos_t *pos ) ; 


stream Target stream 


pos Position-indicator storage 


The fsetpos function sets the file-position indicator for stream to the value of pos, 
which is obtained in a prior call to fgetpos against stream. 


The function clears the end-of-file indicator and undoes any effects of the ungetc 
function on stream. After calling fsetpos, the next operation on stream may be 
either input or output. 


If successful, the fsetpos function returns 0. On failure, the function returns a non- 
zero value and sets errno to one of the following manifest constants (defined in 
ERRNO.H): 

Constant Meaning 


EBADF The object that stream points to is not a valid file handle, or the 
file 1s not accessible. 


EINVAL An invalid stream value was passed. 


Standards: ANSI 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 


fgetpos 
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Example /* FGETPOS.C: This program opens a file and reads bytes at several 
* different locations. 
* / 
HHinclude <stdio.h> 


void main( void ) 


{ 
EDIE *xStream; 
fpos_t pos; 
int val; 
char buffer[2Q]; 
if( (stream = fopen( "fgetpos.c", "rb" )) == NULL ) 
printf( "Trouble opening file\n" ); 
else 
{ 
/* Read some data and then check the position. */ 
fread( buffer, sizeof( char ), 10, stream );- 
if( fgetpos( stream, &pos ) != @ ) 
perror( "“fgetpos error" ); 
else 
{ 
fread( buffer, sizeof( char ), 10, stream ); 
printf( "10 bytes at byte %ld: %.1@s\n", pos, buffer ); 
} 
/* Set a new position and read more data. */ 
pos = 14@; 
if( fsetpos( stream, &pos ) != @ ) 
perror( "fsetpos error” ); 
fread( buffer, sizeof( char ), 10, stream ); 
printf( "1@ bytes at byte 4ld: %.1@s\n", pos, buffer ); 
fclose( stream ); 
J 
} 
Output 10 bytes at byte 10: .C: This p 


10 bytes at byte 14@: FILE * 


Description 


Remarks 


_fsopen 323 
_fsopen 
Opens a stream with file sharing. 


#include <stdio.h> 


#include <share.h> shflag constants 


FILE *_fsopen( const char *filename, const char “mode, int shflag ); 


filename Filename to open 
mode Type of access permitted 
shflag Type of sharing allowed 


The _fsopen function opens the file specified by filename as a stream and pre- 
pares the file for subsequent shared reading or writing, as defined by the mode and 
shflag arguments. 


The character string mode specifies the type of access requested for the file, as 
follows: 


Type Description 


eee 


r Opens for reading. If the file does not exist or cannot be found, the 
_fsopen call will fail. 


Ww Opens an empty file for writing. If the given file exists, its contents 
are destroyed. 


a Opens for writing at the end of the file (appending); creates the file 
first if it does not exist. 


r+ Opens for both reading and writing. (The file must exist.) 
"w+"! Opens an empty file for both reading and writing. If the given file 
exists, its contents are destroyed. 
"at" Opens for reading and appending; creates the file first if 1t does not 


exist. 


Use the "'w" and "w+" types with care, as they can destroy existing files. 


eo? 


When a file is opened with the ''a"' or ''a+"' access type, all write operations occur 
at the end of the file. Although the file pointer can be repositioned using fseek or 
rewind, the file pointer is always moved back to the end of the file before any 
write operation is carried out. Thus, existing data cannot be overwritten. 
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Return Value 


When the "r+", "w+", or ''at+'" access type is specified, both reading and writing 
are allowed (the file is said to be open for “update’”). However, when switching be- 
tween reading and writing, there must be an intervening fsetpos, fseek, or rewind 
operation. The current position can be specified for the fsetpos or fseek operation, 
if desired. 


In addition to the values listed above, one of the following characters can be in- 
cluded in mode to specify the translation mode for new lines: 


Mode Meaning 


t Open in text (translated) mode. In this mode, carriage-return— 
line-feed (CR-LF) combinations are translated into single line 
feeds (LF) on input and LF characters are translated to CR-LF 
combinations on output. Also, CTRL+Z is interpreted as an end- 
of-file character on input. In files opened for reading or 
reading/writing, _fsopen checks for a CTRL+Z at the end of the 
file and removes it, if possible. This is done because using the 
fseek and ftell functions to move within a file that ends with a 
CTRL+Z may cause fseek to behave improperly near the end of 
the file. 

b Open in binary (untranslated) mode; the above translations are 
suppressed. 


If t or b is not given in mode, the translation mode is defined by the default-mode 
variable _fmode. If t or b is prefixed to the argument, the function will fail and 
will return NULL. 


See “Input and Output’ on page 31 for a discussion of text and binary modes. 


The argument shflag is a constant expression consisting of one of the following 
manifest constants, defined in SHARE.H. If SHARE.COM—or SHARE.EXE for 
some versions of DOS—is not installed, DOS ignores the sharing mode. (See your 
system documentation for detailed information about sharing modes.) 


Constant Meaning 


_SH_COMPAT Sets compatibility mode 
_SH_DENYNO Permits read and write access 
_SH_DENYRD Denies read access to file 
_SH_DENYRW Denies read and write access to file 
_SH_DENYWR Denies write access to file 


The _fsopen function should be used only under DOS versions 3.0 and later. 
Under earlier versions of DOS, the shflag argument is ignored. 


The _fsopen function returns a pointer to the stream. A NULL pointer value indi- 
Cates an error. 
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Compatibility Standards: None 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 
See Also fclose, _ fcloseall, _ fdopen, ferror, _ fileno, fopen, freopen, _ open, _ setmode, 


Example 


Output 


_sopen 


/* FSOPEN.C: This program opens files named "data" and "data2". It uses 
* fclose to close "data" and _fcloseall to close all remaining files. 
* / 


dEinclude <stdio.h> 
dFinclude <share.h> 


FILE *stream; 


void main( void ) 
{ 
FILE *stream; 


/* Open output file for writing. Using _fsopen allows us to ensure 
* that no one else writes to the file while we are writing to it. 
* / 

if( (stream = _fsopen( “outfile”, "wt", _SH_DENYWR )) != NULL ) 

{ 

fprintf( stream, "No one else in the network can write " 
"to this file until we are done.\n" ); 
fclose( stream ); 

} 

/* Now others can write to the file while we read it. */ 

System( "type outfile” ); 


No one else in the network can write to this file until we are done. 
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_fstat 


Description Gets information about an open file. 


#include <sys\types.h> 


#include <sys\stat.h> 


int _ fstat( int handle, struct _stat *buffer ); 


handle Handle of open file 
buffer Pointer to structure to store results 
Remarks The _fstat function obtains information about the open file associated with handle 


and stores it in the structure pointed to by buffer. The structure, whose type _ stat 
is defined in SYS\STAT.H, contains the following fields: 


Field Value 

st_ atime Time of last access of file. 

st_ctime Time of creation of file. 

st_dev Either the drive number of the disk containing the file, or handle 
in the case of a device (same as st_rdey). 

st_mode Bit mask for file-mode information. The _S_TFCHR bit is set if 


handle refers to a device. The _S_IFREG bit is set if handle 
refers to an ordinary file. The read/write bits are set according to 
the file’s permission mode. (_S_IFCHR and other constants are 


defined in SYS\ STAT-H.) 
st_mtime Time of last modification of file. 
st_nlink Always 1. 
st_rdev Either the drive number of the disk containing the file, or handle 


in the case of a device (same as st_dev). 
st_size Size of the file in bytes. 


If handle refers to a device, the size and time fields in the _stat structure are not 
meaningful. 


Return Value The _fstat function returns the value 0 if the file-status information is obtained. A 
return value of —1 indicates an error; in this case, errno is set to EBADF, indicat- 
ing an invalid file handle. 
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Compatibility Standards: UNIX 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 


See Also 


Example 


Use _fstat for compatibility with ANSI naming conventions of non-ANSI func- 
tions. Use fstat and link with OLDNAMES.LIB for UNIX compatibility. 


_access, _chmod, _ filelength, _ stat 


/* FSTAT.C: This program uses _fstat to report the size of a file 
* named FSTAT.OUT. 
* / 


dHinclude <io.h> 
d#Hinclude <fcntl.h> 
#Hinclude <time.h> 
#Hinclude <sys\types.h> 
dEinclude <sys\stat.h> 
dFinclude <stdio.h> 
dFinclude <stdlib.h> 
#Hinclude <string.h> 


void main( void ) 
{ 
struct _stat buf; 
int fh, result; 
char bufferL] = "A line to output"; 


if( (fh = _open( "f_stat.out", _O_CREAT | _O_WRONLY | _O_TRUNC )) == -1 ) 
exit( 1 ); 
_write( fh, buffer, strlen( buffer ) ); 


/* Get data associated with "fh": */ 
result = _fstat( fh, &buf ); 


/* Check if statistics are valid: */ 
if( result != @ ) 
printf( "Bad file handle\n" ); 
else 
{ 
printf( "File size : Zid\n", buf.st_size ); 
printf( “Drive number : %4d\n", buf.st_dev ); 
printf( "Time modified : %s", ctime( &buf.st_atime ) ); 
i 
_close( fh ); 
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Output File size : 16 
Drive number : Q 
Time modified : Tue Jun 15 21:38:46 1999 


Description 


Remarks 


Return Value 
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ftell 


Gets the current position of a file pointer. 
#include <stdio.h> 
long ftell( FILE *stream ); 


stream Target FILE structure 


The ftell function gets the current position of the file pointer (if any) associated 
with stream. The position is expressed as an offset relative to the beginning of the 
stream. 


Note that when a file is opened for appending data, the current file position is de- 
termined by the last I/O operation, not by where the next write would occur. For 
example, if a file is opened for an append and the last operation was a read, the file 
position is the point where the next read operation would start, not where the next 
write would start. (When a file is opened for appending, the file position is moved 
to end-of-file before any write operation.) If no I/O operation has yet occurred on 
a file opened for appending, the file position is the beginning of the file. 


The ftell function returns the current file position. The value returned by ftell may 
not reflect the physical byte offset for streams opened in text mode, since text 
mode causes carriage-return—line-feed translation. Use ftell in conjunction with 
the fseek function to return to file locations correctly. On error, the function re- 
turns —1L and errno is set to one of the following constants, defined in ERRNO.H: 


Constant Description 

EBADF Bad file number. The stream argument is not a valid file-handle value 
or does not refer to an open file. 

EINVAL Invalid argument. An invalid stream argument was passed to the 
function. 


On devices incapable of seeking (such as terminals and printers), or when stream 
does not refer to an open file, the return value is undefined. 
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Compatibility Standards: ANSI, UNIX 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 

See Also fgetpos, fseek, _Iseek, _ tell 


Example /* FTELL.C: This program opens a file named FTELL.C for reading and 
* tries to read 100 characters. It then uses ftell to determine the 
* position of the file pointer and displays this position. 
* / 
#tinclude <stdio.h> 
FILE *stream; 


void main( void ) 


{ 
long position; 
char list[100]; 
if( (stream = fopen( "ftell.c", "rb" )) != NULL ) 
{ 
/* Move the pointer by reading data: */ 
fread( list, sizeof( char ), 100, stream ); 
/* Get position after read: */ 
position = ftell( stream ); 
printf( "Position after trying to read 100 bytes: %ld\n", position ); 
fclose( stream ); 
} 
} 


Output Position after trying to read 100 bytes: 100 
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_ ftime 


Description Gets the current time. 


#include <sys\types.h> 


#include <sys\timeb.h> 
void _ ftime( struct _timeb *timeptr ); 


timeptr Pointer to structure defined in SYS\TIMEB.H 


Remarks The _ftime function gets the current time and stores it in the structure pointed to 
by timeptr. The _ timeb structure is defined in SYS\TIMEB.H. It contains four 
fields (dstflag, millitm, time, and timezone), which have the following values: 


Field Value 


dstflag Nonzero if daylight saving time is currently in effect for the local 
time zone. (See _tzset for an explanation of how daylight saving 
time is determined.) 


millitm Fraction of a second in milliseconds. The last digit is always O since 
millitm is incremented to the nearest one-hundredth of a second. 

time Time in seconds since midnight (00:00:00), December 31, 1899. 

timezone Difference in minutes, moving westward, between Universal 


Coordinated Time and local time. The value of timezone is set from 
the value of the global variable _ timezone (see _ tzset). 


Return Value The _ftime function gives values to the fields in the structure pointed to by 
timeptr. It does not return a value. 


Compatibility Standards: None 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 


See Also asctime, ctime, gmtime, localtime, time, _ tzset 
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Example /* FTIME.C: This program uses _ftime to obtain the current time 
* and then stores this time in timebuffer. 
7 / 


dHinclude <stdio.h> 
d#Finclude <sys\timeb.h> 
dFinclude <time.h> 


void main( void ) 


{ 

struct _timeb timebuffer; 

char *xtimeline; 

_ftime( &timebuffer ); 

timeline = ctime( & ( timebuffer.time ) ); 

printf( "The time is %.19s.%hu 4s", 

timeline, timebuffer.millitm, &timeline[20] ); 

} 


Output The time is Tue Jun 15 21:40:34.870 1999 


Description 


Remarks 


Return Value 


Compatibility 


See Also 
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_fullpath 


Makes an absolute path name from a relative path name. 
#include <stdlib.h> 


char *_fullpath( char *buffer, const char *pathname, size_t maxlen ); 
p p 


buffer Full path-name buffer 
pathname Relative path name 
maxlen Length of the buffer pointed to by buffer 


The _fullpath routine converts the partial path stored in pathname to a fully qual- 
ified path that 1s stored in buffer. Unlike _makepath, the _fullpath routine can be 
used with .\ and ..\ in the path. 


If the length of the fully qualified path is greater than the value of maxlen, then 
NULL is returned; otherwise, the address of buffer is returned. 


If the buffer is NULL, —_fullpath will allocate a buffer of _.MAX_ PATH size 
using malloc and the maxlen argument is ignored. It is the caller’s responsibility 
to deallocate this buffer (using free) as appropriate. 


If the pathname argument specifies a disk drive, the current directory of this drive 
is combined with the path. If the drive is not valid, _ fullpath returns NULL. 


The _fullpath function returns a pointer to the buffer containing the absolute path 
(buffer). If there is an error, _fullpath returns NULL. 


Standards: None 
16-Bit:. | DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 


_getcwd, _getdcwd, _makepath, _splitpath 
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Example /* FULLPATH.C: This program demonstrates how _fullpath creates a full 
* path from a partial path. 
*« / 


dEinclude <stdio.h> 
dHinclude <conio.h> 
d#Hinclude <stdlib.h> 
dFinclude <direct.h> 
char full[_MAX_PATH], part[l_MAX_ PATH]; 


void main( void ) 


{ 
while( 1 ) 
{ | 
printf( "Enter partial path or ENTER to quit: ™ ); 
gets( part ); 
if( partl@] == @ ) 
break; 
if( _fullpath( full, part,  _MAX_PATH ) != NULL ) 
printf( "Full path is: %s\n", full ); 
else 
printf( "Invalid path\n" ); 
I 
} 
Output Enter partial path or ENTER to quit: 


Full path is: C:\ 

Enter partial path or ENTER to quit: ..\include 
Full path is: C:\include 

Enter partial path or ENTER to quit: p: 

Full path is: P:\ 

Enter partial path or ENTER to quit: fullpath.c 
Full path is: C:\LIBREF\fullpath.c 

Enter partial path or ENTER to quit: 


Description 


Remarks 
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_fwopen 
Opens a new file stream for a Quick Win window. 
#include <stdio.h> 


FILE * _ fwopen( struct _ wopeninfo *wopeninfo, 
struct _ wsizeinfo *wsizeinfo, char * mode ); 


wopeninfo Pointer to a_ wopeninfo structure 
wsizeinfo Pointer to a _ wsizeinfo structure 
mode Type of access permitted 


The _fwopen function is a high-level call that opens a new Quick Win window, re- 
turning a file-stream pointer. This routine is used only in QuickWin programs; it is 
not part of the Windows API. For full details about QuickWin, see Chapter 8 of 

Programming Techniques (in the Microsoft C/C++ version 7.0 documentation set). 


The _ wopeninfo and _ wsizeinfo structures, declared in STDIO.H, are used to 
pass window initialization information, including the window’s initial size and 
position on the screen. You can pass NULL for these arguments to accept Quick- 
Win defaults or declare variables of these two structure types and fill in their fields. 


If you declare _ wopeninfo and _ wsizeinfo variables, assign the _WINVER 
macro to the _ version field. _WINVER is the current Quick Win version, defined 
in STDIO.H. 


For the _ wopeninfo variable, assign a null-terminated string to the _ title field con- 
taining the desired window title. You can also optionally set the size of the win- 
dow’s screen buffer in the _ wbufsize field. The default is 2,048 bytes, but you can 
pass some other number or the value __ WINBUFINF. This causes the buffer to be 
reallocated continually so that all window output is retained for scrolling. 


For the _ wsizeinfo variable, assign one of the following values to the _ type field: 


Value Meaning 
_WINSIZEMIN Minimize the window 
_WINSIZEMAX Maximize the window 


_WINSIZECHAR Use character coordinates for the window size 
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Return Value 


Compatibility 


See Also 


If the type is__ WINSIZECHAR, you must supply the _x, _y, _h, and _w values 
in the remainder of the structure. They specify the upper-left corner and the height 
and width of the window (in characters). 


The mode parameter is a pointer to the stream I/O mode. The _ fwopen function 
accepts the same mode values as the STDIO.H fopen function: 


Type Description 

oe Opens for reading 

"w" Opens for writing 

wre Opens for both reading and writing 
"w+"! Opens for both reading and writing 


In addition to the values listed above, one of the following characters can be in- 
cluded in mode to specify the translation mode for newline characters: 


Mode Meaning 
t Open in text (translated) mode 
b Open in binary (untranslated) mode 


If t or b is not given in mode, the translation mode is defined by the default-mode 
variable _fmode. If t or b is prefixed to the argument, the function fails and re- 
turns NULL. See “Input and Output” on page 31 for a discussion of text and bi- 
nary modes. 


If _fwopen is successful, the returned stream can be passed to standard STDIO.H 
functions such as fread, fwrite, and fprintf. If you write to a stream and then read 
from it, or if you read from a stream and then write to it, call the STDIO.H rewind 
function between the I/O calls. To close an open window stream, call the 
STDIO.H function fclose. If you have opened a window with _fwopen, you can 
use the _ fileno macro to obtain a file handle, which you can then pass to other 
Quick Win calls, such as _ wsetscreenbuf or _ wsetsize. 


If successful, the _fwopen function returns a stream pointer (FILE *) to the new 
window. A return value of NULL indicates an error. 


Standards: None 
16-Bit: QWIN 
32-Bit: None 


fclose, _fileno, _ wabout, _ wclose, _ wgetfocus, _ wgetscreenbuf, _ wgetsize, 
_wmenuclick, _ wopen, _ wsetfocus, _ wsetscreenbuf, _ wsetsize, _ wyield 
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Example /* FOWPEN.C - Demonstrate opening QuickWin windows with _fwopen */ 


dEinclude <io.h> 
dtinclude <stdio.h> 


#tdefine OPENFLAGS “w" /* Access permission */ 

void main( void ) 

{ 
Struct _wopeninfo wininfo; /* Open information */ 
char wintitleL32] = "QuickWin "; /* Title for window */ 
FILE *wp; /* FILE ptr to window */ 
int nRes; /* 1/0 result */ 


/* Set up window info structure for _fwopen */ 
wininfo._version = _WINVER; 

wininfo._ title = wintitle; 

wininfo._wbufsize = _WINBUFDEF; 


/* Create a new window */ 
/* NULL second argument accepts default size/position */ 
wp = _fwopen( &wininfo, NULL, OPENFLAGS ); 
if( wp == NULL ) 
{ 
printf( "“***ERROR: _fwopen\n" ); 
exite al 9s 
} 


/* Write in the window */ 
nRes = fprintf( wp, "Hello, QuickWin!\n" ); 


/* Close the window */ 
nRes = fclose( wp ); 


exit( @ ); 


338 _—— write 
fwrite 

Description Writes data to a stream. 
#include <stdio.h> 


size_t fwrite( const void *buffer, size_t size, size_t count, FILE *stream ); 


buffer Pointer to data to be written 
size Item size in bytes 
count Maximum number of items to be written 
stream Pointer to FILE structure 
Remarks The fwrite function writes up to count items, of length size each, from buffer to 


the output stream. The file pointer associated with stream (if there is one) is incre- 
mented by the number of bytes actually written. 


If stream is opened in text mode, each carriage return is replaced with a carriage- 
return—line-feed pair. The replacement has no effect on the return value. 


Return Value The fwrite function returns the number of full items actually written, which may 
be less than count if an error occurs. Also, if an error occurs, the file-position in- 
dicator cannot be determined. 


Compatibility Standards: ANSI, UNIX 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 


See Also fread, _ write 


Example 


Output 


/* 


* / 


fwrite 


FREAD.C: This program opens a file named FREAD.OUT and writes 25 
characters to the file. It then tries to open FREAD.OUT and 

read in 25 characters. If the attempt succeeds, the program 
displays the number of actual items read. 


#Finclude <stdio.h> 


void main( void ) 


{ 


FILE *stream; 
char list[30]; 
int 71, numread, numwritten; 


/* Open file in text mode: */ 
if( (stream = fopen( "fread.out", "w+t" )) != NULL ) 


{ 
for ( i= Qs 7 < 25% i4f ) 
Seek ee Ss 
/* Write 25 characters to stream */ 
numwritten = fwrite( list, sizeof( char ), 25, stream ); 
printf( "Wrote %d items\n", numwritten ); 
fclose( stream ); 
} 
else 


printf( "Problem opening the file\n" ); 


if( (stream = fopen( "fread.out", "r+t" )) != NULL ) 


{ 
/* Attempt to read in 25 characters */ 
numread = fread( list, sizeof( char ), 25, stream ); 
printf( “Number of items read = %4d\n", numread ); 
printf( "Contents of buffer = %.25s\n", list ); 
fclose( stream ); 

i; 

else 


printf( "Was not able to open the file\n" ); 


Wrote 25 items 
Number of items read = 25 
Contents of buffer = zyxwvutsrqponml kjihgfedcb 
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340 _ gcvi 


Description 


Remarks 


Return Value 


Compatibility 


See Also 


_ gcvt 


Converts a floating-point value to a string, which it stores in a buffer. 
#include <stdlib.h> Required only for function declarations 


char *_ gcvt( double value, int digits, char *buffer ); 


value Value to be converted 
digits Number of significant digits stored 
buffer Storage location for result 


The _ gevt function converts a floating-point value to a character string (which in- 
cludes a decimal point and a possible sign byte) and stores the string in buffer. The 
buffer should be large enough to accommodate the converted value plus a terminat- 
ing null character (’\0’), which is appended automatically. If a buffer size of signif- 
icant digits + 1 is used, the function will overwrite the end of the buffer. This is 
because the converted string includes a decimal point and can contain sign and ex- 
ponent information. There is no provision for overflow. 


The _ gevt function attempts to produce digits significant digits in decimal format. 


If this is not possible, it produces digits significant digits in exponential format. 
Trailing zeros may be suppressed in the conversion. 


The _ gevt function returns a pointer to the string of digits. There is no error return. 


Standards: UNIX 
16-Bit: DOS, QWIN, WIN 
32-Bit: DOS32X 


Use _ gevt for compatibility with ANSI naming conventions of non-ANSI func- 
tions. Use gevt and link with OLDNAMES.LIB for UNIX compatibility. 


atof, atoi, atol, _ecvt, _fcvt 


Example 


Output 


/* GCVT.C: This program converts -3.1415e5 to its string 


dFinclude <stdlib.h> 
dFinclude <stdio.h> 


void main( void ) 
{ 
char buffer[50]; 
double source = -3.1415e5; 


_gcvt( source, 7, buffer ); 


printf( "source: “4f buffer: 


_gcvt( source, 7, buffer ); 


printf( “source: %e buffer: 


source: -31415@.00000@ buffer: 
source: -3.1415@@e+005 buffer: 


"%s'\n", source, 


"S'\n", source, 


"-314150.' 
"oS LALO S. 


buffer ); 


buffer ); 


_gevt 


representation. */ 
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342 


Description 


Remarks 


Return Value 


_ getactivepage 


_ getactivepage 


Gets the current active page number. 
#include <graph.h> 


short __ far _ getactivepage( void ); 


The _ getactivepage function returns the number of the current active page. 


The function returns the number of the current active video page. All hardware 
combinations support at least one page (page number 0). 


Compatibility Standards: None 
16-Bit: DOS 
32-Bit: None 
See Also _getvideoconfig, _ getvisualpage, _egrstatus, _setactivepage, _setvideomode, 


Example 


_setvisualpage 


/* PAGE.C illustrates video page functions including: 
** _getactivepage _getvisualpage _setactivepage _setvisualpage 
* / 


d#Finclude <conio.h> 
#Finclude <graph.h> 
d#Finclude <stdlib.h> 


void main( void ) 

{ 
Short oldvpage, oldapage, page, row, col, line; 
struct _videoconfig vc; 
char buf [8Q]; 


_getvideoconfig( &vc ); 
if( vc.numvideopages < 4 ) 


exit( 1 ); /* Fail for or monochrome. */ 
Oldapage = _getactivepage(); 
Oldvpage = _getvisualpage(); 


_displaycursor( _GCURSOROFF ); 


_ getactivepage 


/* Draw arrows in different place on each page. */ 
for( page = 1; page < 4; paget+ ) 


{ 
_setactivepage( page ); 
_settextposition( 12, 16 * page ); 
SOUTTEXTE “>> >> 0072" 

} 


while( !_kbhit() ) 
/* Cycle through pages 1 to 3 to show moving image. */ 
for( page = 1; page < 4; paget+ ) 
_setvisualpage( page ); 
_getch(); 


/* Restore original page (normally @) to restore screen. */ 
_setactivepage( oldapage ); 

_setvisualpage( oldvpage ); 

_displaycursor( _GCURSORON ); 
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344 _ getarcinfo 


Description 


Remarks 


Return Value 


Compatibility 


See Also 


Example 


_ getarcinfo 


Determines the endpoints in viewport coordinates of the most recently drawn arc 
or pie. 


#include <graph.h> 


short __ far _ getarcinfo( struct _xycoord __ far *start, 
struct _xycoord __ far “end, struct _xycoord __far *fillpoint ); 


start Starting point of arc 
end Ending point of arc 
fillpoint Point at which pie fill will begin 


The _ getarcinfo function determines the endpoints in viewport coordinates of the 
most recently drawn arc or pie. 


If successful, the _ getarcinfo function updates the start and end _xycoord struc- 
tures to contain the endpoints (in viewport coordinates) of the arc drawn by the 
most recent call to one of the _arc or _ pie functions. 


In addition, fillpoint specifies a point from which a pie can be filled. This is 
useful for filling a pie in a color different from the border color. After a call to 
_getarcinfo, change colors using the _setcolor function. Use the color, along 
with the coordinates in fil/point, as arguments for the _ floodfill function. 


The _ getarcinfo function returns a nonzero value if successful. If neither the _ are 
nor the _ pie function has been successfully called since the last time the screen 
was cleared or a new graphics mode or viewport was selected, the _ getarcinfo 
function returns 0. 


Standards: None 
16-Bit: DOS 
32-Bit: None 


_arc functions, —floodfill, _getvideoconfig, _grstatus, _ pie functions 


See the example for _ are. 


Description 


Remarks 


Return Value 


Compatibility 


See Also 


Example 


_ getbkcolor 345 


_ getbkcolor 


Gets the current background color. 
#include <graph.h> 


long __ far _ getbkcolor( void ); 


The _ getbkcolor function returns the current background color. The default is 0. 


In a color text mode such as_TEXTC80, _ setbkcolor accepts, and _ getbkcolor 
returns, a color index. For example, _ setbkcolor(2L) sets the background color to 
color index 2. The actual color displayed depends on the palette mapping for color 
index 2. The default for color index 2 is green in a color text mode. 


In a color graphics mode such as_ERESCOLOR, _ setbkcolor accepts, and 
_getbkcolor returns, a color value (as used in _remappalette). The value for the 
simplest background colors is given by the manifest constants defined in the 
GRAPH.H include file. For example, _setbkcolor( _GREEN) sets the back- 
ground color in a graphics mode to green. These manifest constants are provided 
as a convenience in defining and manipulating the most common colors. In 
general, the actual range of colors is much greater. 


In most cases, whenever a color argument is long, it refers to a color value, and 
whenever it is short, it refers to a color index. The two exceptions are _setbkcolor 
and _ getbkcolor, described above. For a more complete discussion of colors, see 
_remappalette. 


The function returns the current background color. There is no error return. 


Standards: None 
16-Bit: DOS 
32-Bit: None 


_remappalette, _setbkcolor 


See the example for _ getcolor. 


346 getc, getchar 


Description 


Remarks 


Return Value 


Compatibility 


See Also 


getc, getchar 


Reads a character from a stream (getc), or gets a character from stdin (getchar). 
#include <stdio.h> 


int getc( FILE “stream ); 


int getchar( void ); 


stream Current stream 


The getc routine reads a single character from the stream position and increments 
the associated file pointer (if there 1s one) to point to the next character. The 
getchar routine is identical to getc(stdin). 


The getc and getchar routines are similar to fgetc and _fgetchar, respectively, 
but are implemented both as macros and functions. 


Both gete and getchar return the character read. A return value of EOF indicates 
an error or end-of-file condition. Use ferror or feof to determine whether an error 
or end-of-file occurred. 


getc 

Standards: ANSI, UNIX 

16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 

getchar 

Standards: ANSI, UNIX 

16-Bit: DOS, QWIN 

32-Bit: DOS32xX 


{getc, _fgetchar, _ getch, _ getche, putc, putchar, ungetc 
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Example /* GETC.C: This program uses getchar to read a single line of input 
* from stdin, places this input in buffer, then terminates the 
* string before printing it to the screen. 
* / 


dFinclude <stdio.h> 


void main( void ) 


{ 
char bufferLl81]; 
int i, ch; 
printf( "Enter a line: " ); 
/* Read in single line from “stdin": */ 
for( i = @; (i < 80) && ((ch = getchar()) != EOF) && (ch != '\n'); i++ ) 

bufferLi] = ch; 

/* Terminate string with null character: */ 
bufferlLi] = '\Q@'; 
printf( "%s\n", buffer ); 

} 

Output Enter a line: This is a line of text. 


This is a line of text. 


348  —_getch, getche 


Description 


Remarks 


Return Value 


Compatibility 


See Also 


_getch, getche 


Get a character from the console without echo (_ getch) or with echo (_ getche). 
#include <conio.h> Required only for function declarations 


int _ getch( void ); 


int _ getche( void ); 


The _ getch function reads a single character from the console without echoing. 
The _ getche function reads a single character from the console and echoes the 
character read. Neither function can be used to read CTRL+C. 


When reading a function key or cursor-moving key, the _getch and _ getche func- 
tions must be called twice; the first call returns 0 or OxEO, and the second call re- 
turns the actual key code. 


Both the _ getch and _ getche functions return the character read. There is no error 
return. 


Standards: None 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 


_cgets, getchar, _ungetch 


Example /* GETCH.C: This program reads characters from the keyboard until it 
* receives a 'Y' or ‘y'. 


* / 


#Hinclude <conio.h> 
#Hinclude <ctype.h> 
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void main( void ) 


{ 
ieee “OAs 
_cputs( "Type 'Y' when finished typing keys: " ); 
do 
{ 
ch = _getch(); 
ch = toupper( ch ); 
} while( ch != 'Y' ); 
_putch( ch ); 
_putch( ‘\r' ); /* Carriage return */ 
_putch( ‘\n' ); /* Line feed * / 
} 


Output Type 'Y' when finished typing keys: Y 


350 _getcolor 
_ getcolor 
Description Gets the current color. 
#include <graph.h> 


short __ far _ getcolor( void ); 


Remarks The _ getcolor function returns the current graphics color index. The default is the 
highest legal index in the current palette. 


Return Value The _ getcolor function returns the current color index. 
Compatibility Standards: None 

16-Bit: DOS 

32-Bit: None 
See Also _setcolor 


Example /* OUTTXT.C: This example illustrates text output functions: 


* _gettextcolor _getbkcolor _gettextposition _outtext 
* _settextcolor _setbkcolor -_settextposition 
* / 


d#Ainclude <conio.h> 
d#Finclude <stdio.h> 
#Hinclude <graph.h> 


char buffer [80]; 


void main( void ) 
{ 
/* Save original foreground, background, and text position. */ 
short blink, fgd, oldfgd; 
long bgd, oldbgd; 
struct _rccoord oldpos; 


/* Save original foreground, background, and text position. */ 


oldfgd = _gettextcolor(); 
oldbgd = _getbkcolor(); 
oldpos = _gettextposition(); 


_clearscreen( _GCLEARSCREEN ); 


_ getcolor 


/* First time no blink, second time blinking. */ 
for( blink = @; blink <= 16; blink += 16 ) 


{ 
/* Loop through 8 background colors. */ 
for( bgd = @; bad < 8; bgd++ ) 
{ 
_setbkcolor( bad ); 
_settextposition( (short)bgd + ((blink / 16) * 9) + 3, 1 ); 
_settextcolor( 7 ); 
sprintf(buffer, "Back: %d Fore:", bgd ); 
_outtext( buffer ); 
/* Loop through 16 foreground colors. */ 
for( fgd = @; fgd < 16; fgdt++ ) 
{ 
_settextcolor( fgd + blink ); 
sprintf( buffer, " %2d ", fgd + blink ); 
_outtext( buffer ); 
} 
} 
} 
_getch(); 


/* Restore original foreground, background, and text position. */ 
_settextcolor( oldfgd ); 

_setbkcolor( oldbgd ); 

_clearscreen( _GCLEARSCREEN ); 

_settextposition( oldpos.row, oldpos.col ); 


351 


352 _ getcurrentposition Functions 


Description 


Remarks 


Return Value 


_ getcurrentposition Functions 


Get the current position and return it as a structure. 
#include <graph.h> 


struct _xycoord __far _ getcurrentposition( void ); 


struct _wxycoord __ far _ getcurrentposition_ w( void ); 


The _ getcurrentposition functions return the coordinates of the current graphics 
output position. The _ getcurrentposition function returns the position as an 
_xycoord structure, defined in GRAPH.H. 


The _ xycoord structure contains the following elements: 


Element Description 
short xcoord x coordinate 
short ycoord y coordinate 


The _ getcurrentposition_ w function returns the position as a __wxycoord struc- 
ture, defined in GRAPH.H. 


The _ wxycoord structure contains the following elements: 


Element Description 
double wx window x coordinate 
double wy window y coordinate 


The current position can be changed by the _lineto, _ moveto, and _ outgtext 
functions. 


The default position, set by _setvideomode, _ setvideomoderows, or 
_setviewport, is the center of the viewport. 


Only graphics output starts at the current position; these functions do not affect 
text output, which begins at the current text position. (See _ settextposition for 
more information.) 


The _ getcurrentposition functions return the coordinates of the current graphics 
output position. There is no error return. 
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Compatibility Standards: None 
16-Bit: DOS 
32-Bit: None 
See Also _grstatus, _lineto functions, _moveto functions, _outgtext 


Example /* GCURPOS.C: This program sets a random current location, then gets that 
* location with _getcurrentposition. 
* / 


#Hinclude <stdio.h> 
#Hinclude <stdlib.h> 
#Hinclude <conio.h> 
#Hinclude <graph.h> 


char buffer[255]; 


void main( void ) 

{ 
struct _videoconfig vc; 
struct _xycoord position; 


/* Find a valid graphics mode. */ 

if( ! setvideomode( _MAXRESMODE ) ) 
exit( 1 ); 

_getvideoconfig( &vc ); 


/* Move to random location and report that location. */ 

_moveto( rand() % vc.numxpixels, rand() % vc.numypixels ); 

position = _getcurrentposition(); 

sprintf( buffer, "x = 4d, y = 4d", position.xcoord, position.ycoord ); 
_settextposition( 1, 1 ); 

_outtext( buffer ); 


_getch(); 
_setvideomode( _DEFAULTMODE ); 


354 _getcwd 


Description 


Remarks 


Return Value 


_ getcwd 


Gets the current working directory. 
#include <direct.h> Required only for function declarations 
char *_ getcwd( char *buffer, int maxlen ); 


buffer Storage location for path name 


maxlen Maximum length of path name 


The _ getewd function gets the full path name of the current working directory for 
the default drive and stores it at buffer. The integer argument maxlen specifies the 
maximum length for the path name. An error occurs if the length of the path name 
(including the terminating null character) exceeds maxlen. 


The buffer argument can be NULL; a buffer of at least size maxlen (more only if 
necessary) will automatically be allocated, using malloc, to store the path name. 
This buffer can later be freed by calling free and passing it the _ getewd return 
value (a pointer to the allocated buffer). 


Note that _ getewd returns a string that represents the path name of the current 
working directory. If the current working directory 1s set to the root, the string will 
end with a backslash (\). If the current working directory is set to a directory other 
than the root, the string will end with the name of the directory and not with a 
backslash. 


The _ getewd function returns a pointer to buffer. A NULL return value indicates 
an error, and errno is set to one of the following values: 


Value Meaning 


ENOMEM Insufficient memory to allocate maxlen bytes (when a NULL 
argument is given as buffer) 


ERANGE Path name longer than maxlen characters 
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Compatibility Standards: UNIX 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 


Use _ getewd for compatibility with ANSI naming conventions of non-ANSI func- 
tions. Use getewd and link with OLDNAMES.LIB for UNIX compatibility. 


See Also _chdir, _ mkdir, _ rmdir 


Example /* This program places the name of the current directory in the buffer 
array, then displays the name of the current directory on the screen. 
Specifying a length of _MAX_DIR leaves room for the longest legal 

* directory name. 

* / 


x * 


deinclude <direct.h> 
#Hinclude <stdlib.h> 
dFinclude <stdio.h> 


void main( void ) 


t 
char bufferL_MAX_DIR]; 
/* Get the current working directory: */ 
if( _getcwd( buffer, _MAX_DIR ) == NULL ) 
perror( "_getcwd error” ); 
else 
printft? “~s\n",, buffer >: 
} 


Output C:\LIBREF 


356  _ getdewd 


Description 


Remarks 


Return Value 


_ getdcwd 


Gets full path name of current working directory on the specified drive. 
#include <direct.h> Required only for function declarations 


char *_getdcwd( int drive, char *buffer, int maxlen ); 


drive Disk drive 
buffer Storage location for path name 
maxlen Maximum length of path name 


The _ getdewd function gets the full path name of the current working directory 
on the specified drive and stores it at buffer. The argument maxlen specifies the 
maximum length for the path name. An error occurs if the length of the path name 
(including the terminating null character) exceeds maxlen. 


The drive argument specifies the drive (0 = default drive, 1=A, 2=B, etc.). The 
buffer argument can be NULL; a buffer of at least size maxlen (more only if neces- 
sary) will automatically be allocated, using malloc, to store the path name. This 
buffer can later be freed by calling free and passing it the _ getdewd return value 
(a pointer to the allocated buffer). 


Note that _ getdewd returns a string that represents the path name of the current 
working directory. If the current working directory is set to the root, the string will 
end with a backslash (\). If the current working directory is set to a directory other 
than the root, the string will end with the name of the directory and not with a 
backslash. 


The _ getdewd function returns buffer. A NULL return value indicates an error, 
and errno is set to one of the following values: 


Value Meaning 


ENOMEM Insufficient memory to allocate maxlen bytes (when a NULL 
argument is given as buffer) 


ERANGE Path name longer than maxlen characters 


_ getdcwd 


Compatibility Standards: None 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 

See Also _chdir, _ getcwd, _ getdrive, _mkdir, _ rmdir 


Example 


/* GETDRIVE.C illustrates drive functions including: 
** _getdrive _chdrive _getdcwd 
*« / 


fHinclude <stdio.h> 
fFinclude <conio.h> 
#Hinclude <direct.h> 
fHinclude <stdlib.h> 


void main( void ) 

{ 
int ch, drive, curdrive; 
Static char pathL_MAX_ PATH]; 


/* Save current drive. */ 
curdrive = _getdrive(); 


printf( “Available drives are: \n" ); 


/* If we can switch to the drive, it exists. */ 
for( drive = 1; drive <= 26; drivet+ ) 
if( !_chdrive( drive ) ) 
printt( “Zoe -"y drive 4° 7A" = |) 


while( 1 ) 
{ 
printf( "\nType drive letter to check or ESC to quit: " ); 
ch = _getch(); 
Lt ch. ==] 27° 3} 
break; 
if( isalpha( ch ) ) 
_putch( ch ); 
if( _getdcwd( toupper( ch ) - 'A' + 1, path, _MAX_PATH ) != NULL ) 
printf( "\nCurrent directory on that drive is 4s\n", path ); 
} 


/* Restore original drive. This is only necessary for DOS.*/ 
_chdrive( curdrive ); 
printf( “\n" ); 
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Output 


_ getdcwd 


Available drives are: 


As: Be Cs 

Type drive letter 
Type drive letter 
Current directory 


Type drive letter 
Current directory 


Type drive letter 


to 
to 
on 


to 
on 


tO 


check or ESC to quit: q 
check or ESC to quit: a 
that drive is A:\ 


check or ESC to quit: c 
that drive is C:\LIBREF 


check or ESC to quit: 


Description 


Remarks 
Return Value 


Compatibility 


See Also 


Example 


_ getdrive 


_ getdrive 


Gets the current disk drive. 
#include <direct.h> 


int _ getdrive( void ); 


The _ getdrive function returns the current (default) drive (1=A, 2=B, etc.). 
The return value is stated above. There is no error return. 


Standards: None 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 


_chdrive, _dos_getdrive, _dos_setdrive, _getcwd, _ getdcwd 


See the example for _ getdcwd. 
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360 getenv 


Description 


Remarks 


Return Value 


Compatibility 


See Also 


getenv 


Gets a value from the current environment. 
#include <stdlib.h> Required only for function declarations 
char *getenv( const char *varname ); 


varname Name of environment variable 


The getenv function searches the list of environment variables for an entry corre- 
sponding to varname. Environment variables define the environment in which a 
process executes. (For example, the LIB environment variable defines the default 
search path for libraries to be linked with a program.) Because the getenv function 
is case sensitive, the varname variable should match the case of the environment 
variable. 


The getenv function returns a pointer to an entry in the environment table. It is, 
however, only safe to retrieve the value of the environment variable using the re- 
turned pointer. To modify the value of an environmental variable, use the _ putenv 
function. 


The getenv and _ putenv functions use the copy of the environment contained in 
the global variable environ to access the environment. Programs that use the envp 
argument to main and the _ putenv function may retrieve invalid information. The 
safest programming practice is to use getenv and _ putenv. 


The getenv function operates only on the data structures accessible to the run-time 
library and not on the environment “segment” created for the process by the oper- 
ating system. 


The getenv function returns a pointer to the environment table entry containing the 
current string value of varname. The return value is NULL if the given variable is 
not currently defined. 


Standards: ANSI, UNIX 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 


_putenv 


Example 


Output 


getenv 


/* GETENV.C: This program uses getenv to retrieve the LIB environment 
* variable and then uses _putenv to change it to a new value. 
2 / 


d4Finclude <stdlib.h> 
4Ainclude <stdio.h> 


void main( void ) 


{ 
char *libvar; 
/* Get the value of the LIB environment variable. */ 
libvar = getenv( "LIB" ); 
if( libvar != NULL ) 
printf( "Original LIB variable is: 4s\n", libvar ); 
/* Attempt to change path. Note that this only affects the environment 
* variable of the current process. The command processor's environment 
* 1S not changed. 
* / 
_putenv( “"LIB=c:\\mylib;c:\\yourlib" ); 
/* Get new value. */ 
libvar = getenv( "LIB" ); 
if( libvar != NULL ) 
printf( "New LIB variable is: 4s\n", libvar ); 
} 


Original LIB variable is: C:\LIB 
New LIB variable is: c:\mylib;c:\yourlib 
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362  _ getfillmask 


Description 


Remarks 


Return Value 


Compatibility 


See Also 


_ getfillmask 


Gets the current fill mask for some graphics routines. 
#include <graph.h> 
unsigned char __ far * __ far _ getfillmask( unsigned char __ far *mask ); 


mask Mask array 


Some graphics routines (_ ellipse, _ floodfill, _ pie, _ polygon, and _ rectangle) 
can fill part or all of the screen with the current color. The fill mask controls the 
pattern used for filling. 


The _ getfillmask function returns the current fill mask. The mask is an 8-by-8-bit 
array, in which each bit represents a pixel. If the bit is 1, the corresponding pixel is 
set to the current color; if the bit is 0, the pixel is left unchanged. The mask is re- 
peated over the entire fill area. If no fill mask is set, or if mask is NULL, a solid 
(unpatterned) fill is performed using the current color. 


If no mask is set, the function returns NULL. Otherwise, it returns the current fill 
mask. 


Standards: None 
16-Bit: DOS 
32-Bit: None 


_ ellipse functions, —floodfill, _ pie functions, _ polygon functions, _rectangle 
functions, _ setfillmask 
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Example /* GFILLMSK.C: This program illustrates _getfillmask and _setfillmask. */ 


4#Ainclude <conio.h> 
HHinclude <stdlib.h> 
#Finclude <graph.h> 


void ellipsemask( short xl, short yl, short x2, short y2, char __far *newmask ); 
unsigned char mask1[8] 


unsigned char mask2[8] 
char oldmask[8]; 


{ @x43, @x23, @x7c, Oxf7, O@x8a, Ox4d, O@x78, x39 }; 
{ 0x18, @xad, @xc®, @x79, Oxf6, @xc4, Oxa8, Qx23 }; 


void main( void ) 
{ 


int loop; 


/* Find a valid graphics mode. */ 
if( !_setvideomode( _MAXRESMODE ) ) 
exit( 1 ); 


/* Set first fill mask and draw rectangle. */ 
_setfillmask( maskl ); 

_rectangle( _GFILLINTERIOR, 20, 20, 100, 100 ); 
_getch(); 


/* Call routine that saves and restores mask. */ 
ellipsemask( 60, 60, 150, 150, mask2 ); 
_getch(); 


/* Back to original mask. */ 
_rectangle( _GFILLINTERIOR, 120, 120, 190, 190 ); 
_getch(); 


_setvideomode( _DEFAULTMODE ); 
exit( @ ); 
} 


/* Draw an ellipse with a specified fill mask. */ 
void ellipsemask( short xl, short yl, short x2, short y2, char __far *newmask ) 


{ 
unsigned char savemask[8]; 
_getfillmask( savemask ); /* Save mask * / 
_setfillmask( newmask ); /* Set new mask * / 
—ellipse( _GFILLINTERIOR, xl, yl, x2, y2 ); /* Use new mask * / 
_setfillmask( savemask ); /* Restore original */ 


364 _ getfontinfo 
_ getfontinfo 
Description Gets the current font characteristics. 
#include <graph.h> 
short __ far _ getfontinfo( struct _fontinfo __ far *fontbuffer ); 


fontbuffer Buffer to hold font information 


Remarks The _ getfontinfo function gets the current font characteristics and stores them in a 
_fontinfo structure, defined in GRAPH.H. 


The _ fontinfo structure contains the following elements: 


Element Contents 
int type Specifies vector (1) or bitmapped (0) font 
int ascent Specifies pixel distance from top to baseline 
int pixwidth Specifies the character width in pixels; 0 indicates a 
proportional font 
int pixheight Specifies the character height in pixels 
int avgwidth Specifies the average character width in pixels 
char filename [81] Specifies the filename, including the path 
char facename [32] Specifies the font name 
Return Value The _ getfontinfo function returns a negative number if a font has not been regis- 


tered or loaded. 


Compatibility Standards: None 
16-Bit: DOS 
32-Bit: None 

See Also _getgtextextent, _ outgtext, _registerfonts, _setfont, _setgtextvector, 
_unregisterfonts 


Example See the example for _outgtext. 


Description 


Remarks 


Return Value 


Compatibility 


See Also 


Example 


_ getgtextextent 365 


_ getgtextextent 


Gets the width in pixels of font-based text. 
#include <graph.h> 
short __ far _ getgtextextent( const char __ far “text ); 


text Text to be analyzed 


The _ getgtextextent function returns the width in pixels that would be required to 
print the text string using _ outgtext with the current font. 


This function is particularly useful for determining the size of text that uses propor- 
tionally spaced fonts. 


The _ getgtextextent function returns the width in pixels. It returns —1 if a font has 
not been registered. 


Standards: None 
16-Bit: DOS 
32-Bit: None 


_getfontinfo, _outgtext, _registerfonts, _setfont, _unregisterfonts 


See the example for _ outgtext. 


366  _ getgtextvector 


Description 


Remarks 


Return Value 


Compatibility 


See Also 


_ getgtextvector 


Changes the orientation of font text output. 
#include <graph.h> 


struct _xycoord __far _ getgtextvector( void ); 


The _ getgtextvector function gets the current orientation for font text output. The 
current orientation is used in calls to the _ outgtext function. 


The text-orientation vector, which determines the direction of font-text rotation on 
the screen, is returned in a structure of type _xycoord. The xcoord and ycoord 
members of the structure describe the vector. The text-rotation options are shown 
below: 


(x, y) Text Orientation 

(1,0) Horizontal text (default) 

(0,1) Rotated 90 degrees counterclockwise 
(-1,0) Rotated 180 degrees 

(0,-1) Rotated 270 degrees counterclockwise 


The _ getgtextvector function returns the current text-orientation vector in a struc- 
ture of type _ xycoord. 


Standards: None 
16-Bit: DOS 
32-Bit: None 


_getgtextextent, _ grstatus, _outgtext, _setfont, _setgtextvector 


Description 


Remarks 


Return Value 
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_ getimage Functions 


Store images in buffers. 
#include <graph.h> 


void __ far _ getimage( short x/, short y/, short x2, short y2, 
char __ huge *image ); 


void __ far _ getimage_w( double wx/, double wy/, double wx2, double wy2, 
char __ huge *image ); 


void __ far _ getimage_ wxy( struct_ wxycoord __ far *pwxy/, 
struct_ wxycoord __ far *pwxy2, char __ huge “image ); 


xI,yl Upper-left corner of bounding rectangle 
x22 Lower-right corner of bounding rectangle 
wxl, wyl Upper-left corner of bounding rectangle 
wx2, wy2 Lower-right corner of bounding rectangle 
pwxyl Upper-left corner of bounding rectangle 
pwxy2 Lower-right corner of bounding rectangle 
image Storage buffer for screen image 


The _ getimage functions store the screen image defined by a specified bounding 
rectangle into the buffer pointed to by image. 


The _ getimage function defines the bounding rectangle with the view coordinates 
(x1, yl) and (x2, y2). 


The _ getimage_ w function defines the bounding rectangle with the window 
coordinates (wx/, wy/) and (wx2, wy2). 


The _ getimage_ wxy function defines the bounding rectangle with the window- 
coordinate pairs pwxy/ and pwxy2. 


The buffer must be large enough to hold the image. You can determine the size by 


calling the appropriate _imagesize function at run time, or by using the formula 
described on the _imagesize reference page. 


None. Use _ grstatus to check success. 


368 #_ getimage Functions 
Compatibility Standards: None 
16-Bit: DOS 
32-Bit: None 
See Also _grstatus, _imagesize functions, _ putimage functions 
Example /* GIMAGE.C: This example illustrates animation routines including: 


* 


* / 


4tinclude 
#Hinclude 
#Hinclude 
#tinclude 
#tinclude 


Short ac 
char *de 


void exi 


void mai 
{ 
char 
long 
shor 


if( 


/* M 
imsi 
buf f 
if ( 


_set 
for 


af 


_imagesize _getimage _putimage 


<conio.h> 
<stddef .h> 
<stdlib.h> 
<malloc.h> 
<graph.h> 


tion[5] 
scripl5] 


{ _GPSET, _GPRESET, _GXOR, _GOR, _GAND } 
{ "PSET ee "PRESET", "YOR i "OR ee "AND we } 


tfree( char __huge *buffer ); 


n( void ) 


__huge *buffer; /* Far pointer (with _fmalloc) could be used. */ 
imsize; 
ti, xX, y = 30; 


! setvideomode( _MAXRESMODE ) ) 
exit( 1 ); 


easure the image to be drawn and allocate memory for it. */ 
ze = (size_t)_imagesize( -16, -16, +16, +16 ); 
er = _halloc( imsize, sizeof( char ) ); 
buffer == (char __far *)NULL ) 
exit( 1 ); 


color( 3 ); 
Ci Nee — ae © ees Vi les a Oc 


/* Draw ellipse at new position and get a copy of it. */ 
xX = 50; y t= 40; 


_ellipse( _GFILLINTERIOR, x - 15, y - 15, x + 15, y +15 ); 
_getimage( x - 16, y - 16, x + 16, y + 16, buffer ); 


if( _grstatus() ) 
exitfree( buffer ); /* Quit on error */ 
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/* Display action type and copy a row of ellipses with that type. */ 
_settextposition( 1, 1 ); 

_outtext( descripLi] ); 

while( x < 26@ ) 


{ 
Xe 55 
_putimage( x - 16, y - 16, buffer, actionLi] ); 
if( _grstatus() < @ ) /* Ignore warnings, quit on errors. */ 
exitfree( buffer ); 
} 
_getch(); 


} 
exitfree( buffer ); 
} 


void exitfree( char __ huge *buffer ) 


{ 


_hfree( buffer ); 
exit( !_setvideomode( _DEFAULTMODE ) ); 


370  _getlinestyle 


Description 


Remarks 


Return Value 


_ getlinestyle 


Gets the current line style. 
#include <graph.h> 


unsigned short __ far _ getlinestyle( void ); 


Some graphics routines (_lineto, _ polygon, and _rectangle) output straight lines 
to the screen. The type of line can be controlled with the current line-style mask. 


The _ getlinestyle function returns the current line-style mask. The mask is a 16- 
bit array in which each bit represents a pixel in the line being drawn. If the bit is 1, 
the corresponding pixel is set to the color of the line (the current color). If the bit is 
0, the corresponding pixel is left unchanged. The mask is repeated over the length 
of the line. The default mask is OxXFFFF (a solid line). 


If no mask has been set, _ getlinestyle returns the default mask. 


Compatibility Standards: None 
16-Bit: DOS 
32-Bit: None 
See Also _lineto functions, _ polygon functions, _ rectangle functions, _setlinestyle, 


Example 


_setwritemode 


/* GLINESTY.C: This program illustrates _setlinestyle and _getlinestyle. */ 
#tinclude <conio.h> 
#Hinclude <stdlib.h> 
#Hinclude <graph.h> 


void zigzag( short xl, short yl, short size ); 
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void main( void ) 


{ 
/* Find a valid graphics mode. */ 
if( ! setvideomode( _MAXCOLORMODE ) ) 
exit( 1 ); 
/* Set line style and draw rectangle. */ 
_setlinestyle( Qx4d ); 
_rectangle( _GBORDER, 10, 10, 60, 60 ); 
_getch(); 
/* Draw figure with function that changes and restores line style. */ 
zigzag( 100, 100, 90 ); 
_getch(); 
/* Original style reused. */ 
_rectangle( _GBORDER, 190, 190, 130, 130 ); 
_getch(); 
_setvideomode( _DEFAULTMODE ); 
i; 


/* Draw box with changing line styles. Restore original style. */ 
void zigzag( short xl, short yl, short size ) 
{ 
short x, y, oldcolor; 
unsigned short oldstyle; 
unsigned short style[16] = { @xQ001, @x0003, O@x0007, OxQ00f, 
QOx001f, Ox0O3F, OxQ0/7f, OxdOff, 
OxOlff, OxO3ff, OxO7ff, OxOfff, 
Oxlfff, Ox3fff, Ox7fff, Oxffff }; 


oldcolor = _getcolor(); 

oldstyle = _getlinestyle(); /* Save old line style. * / 
TORC. S30) @332 MX Sizes Xk. t=] 8. yy tS: 

{ 


_setcolor( x % 16 ); 
_setlinestyle( style[x % 16] ); /* Set and use new line styles */ 
_rectangle( _GBORDER, xl - x, yl - y, xl +x, yl t+y ); 
ii 
_setlinestyle( oldstyle ); /* Restore old line style. * / 
_setcolor( oldcolor ); 


372  _getphyscoord 


Description 


Remarks 


Return Value 


Compatibility 


See Also 


Example 


_ getphyscoord 


Gets physical coordinates. 
#include <graph.h> 
struct _xycoord __ far _ getphyscoord( short x, short y ); 


x,y View coordinates to translate 


The _ getphyscoord function translates the view coordinates (x, y) to physical 
coordinates and returns them in an _ xycoord structure, defined in GRAPH.H. 


The _xycoord structure contains the following elements: 


Element Description 
short xcoord x coordinate 
short ycoord y coordinate 
None. 


Standards: None 
16-Bit: DOS 
32-Bit: None 


_getviewcoord functions, _grstatus, _setvieworg, _setviewport 


See the example for _setwindow. 
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_ getpid 
Description Gets the process identification. 
#include <process.h> Required only for function declarations 


int _ getpid( void ); 


Remarks The _ getpid function returns the process ID, an integer that uniquely identifies the 
calling process. 
Return Value The _ getpid function returns the process ID. There is no error return. 
Compatibility Standards: UNIX 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 


Use _ getpid for compatibility with ANSI naming conventions of non-ANSI func- 
tions. Use getpid and link with OLDNAMES.LIB for UNIX compatibility. 


See Also _mktemp 


Example /* GETPID.C: This program uses _getpid to obtain the process ID and 
* then prints the ID. 
* / 


#Hinclude <stdio.h> 
#Hinclude <process.h> 


void main( void ) 


{ 
/* If run from DOS, shows different ID for DOS than for DOS shell. 
* If execed or spawned, shows ID of parent. 
* / 
printf( "\nProcess id of parent: %d\n", _getpid() ); 
} 


Output Process id of parent: 828 


374  _ getpixel Functions 


Description 


Remarks 


Return Value 


Compatibility 


See Also 


_ getpixel Functions 


Get pixel values. 
#include <graph.h> 


short __ far _ getpixel( short x, short y ); 


short __ far _ getpixel_ w( double wx, double wy ); 


x,y Pixel position 


wx, wy | Pixel position 


The functions in the _ getpixel family return the pixel value (a color index) at a 
specified location. The _ getpixel function uses the view coordinate (x, y). The 

_ getpixel_w function uses the window coordinate (wx, wy). The range of possible 
pixel values is determined by the current video mode. The color translation of 
pixel values is determined by the current palette. 


If successful, the function returns the color index. If the function fails (for ex- 
ample, the point lies outside the clipping region, or the program is in a text mode), 
it returns —1. 


Standards: None 
16-Bit: DOS 
32-Bit: None 


_getvideoconfig, _grstatus, _remapallpalette, _remappalette, 
_selectpalette, _setpixel functions, _setvideomode 


Example 
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/* GPIXEL.C: This program assigns different colors to randomly 
* selected pixels. 
* / 


dHinclude <conio.h> 
d#Hinclude <stdlib.h> 
#Hinclude <graph.h> 


void main( void ) 

{ 
Short xvar, yvar; 
struct _videoconfig vc; 


/* Find a valid graphics mode. */ 

if( ! setvideomode( _MAXCOLORMODE ) ) 
exit( 1 ); 

_getvideoconfig( &vc ); 


/* Draw filled ellipse to turn on certain pixels. */ 
_ellipse( _GFILLINTERIOR, vc.numxpixels / 6, vc.numypixels / 6, 
vc.numxpixels / 6 * 5, vc.numypixels / 6 * 5 ); 


/* Draw random pixels in random colors... */ 
while( !_kbhit() ) 
{ 


/* ...but only if they are already on (inside the ellipse). */ 
Xvar = rand() % vc.numxpixels; 
yvar = rand() % vc.numypixels; 
if( _getpixel( xvar, yvar ) != @ ) 
{ 
_setcolor( rand() % 16 ); 
_setpixel( xvar, yvar ); 


} 
_getch(); /* Throw away the keystroke. */ 


_setvideomode( _DEFAULTMODE ); 
exit( @ ); 


376 gets 


Description 


Remarks 


Return Value 


Compatibility 


See Also 


Example 


gets 


Gets a line from the stdin stream. 
#include <stdio.h> 
char “gets( char *buffer ); 


buffer Storage location for input string 


The gets function reads a line from the standard input stream stdin and stores it in 
buffer. The line consists of all characters up to and including the first newline char- 
acter (\n). The gets function then replaces the newline character with a null charac- 
ter (’\0’) before returning the line. In contrast, the fgets function retains the 
newline character. 


If successful, the gets function returns its argument. A NULL pointer indicates an 
error or end-of-file condition. Use ferror or feof to determine which one has 
occurred. 


Standards: ANSI, UNIX 
16-Bit: DOS, QWIN 
32-Bit: DOS32X 
fgets, fputs, puts 

/* GETS.C */ 


dtinclude <stdio.h> 


{ 


} 


void main( void ) 
char line[81]; 
printf( "Input a string: " ); 


gets( line ); 
printf( "The line entered was: %s\n", line ); 
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Output Input a string: This is a string 
The line entered was: This is a string 


378 _ gettextcolor 


Description 


Remarks 


Return Value 


Compatibility 


See Also 


Example 


_ gettextcolor 


Gets the current text color. 
#include <graph.h> 


short __far _ gettextcolor( void ); 


The _ gettextcolor function returns the color index of the current text color. The 
text color is set by the _settextcolor function and affects text output with the 
_outtext and _outmem functions only. The _setcolor function sets the color for 
font text output using the _outgtext function. 


The default is 7 in text modes; it is the highest legal color index of the current 
palette in graphics modes. 


The _ gettextcolor function returns the color index of the current text color. 


Standards: None 
16-Bit: DOS 
32-Bit: None 


_getvideoconfig, _outmem, _outtext, _remappalette, _selectpalette, 
_setcolor, —settextcolor 


See the example for _ gettextposition. 


Description 


Remarks 


Return Value 


Compatibility 


See Also 


Example 
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_ gettextcursor 


Gets the current cursor attribute. 
#include <graph.h> 


short __ far _ gettextcursor( void ); 
The _ gettextcursor function returns the current cursor attribute (1.e., the shape). 
This function works only in text video modes. 


The function returns the current cursor attribute, or —1 if an error occurs (such as a 
call to the function in a graphics mode). 


Standards: None 
16-Bit: DOS 
32-Bit: None 


_displaycursor, _grstatus, _settextcursor 


See the example for _settextcursor. 


380  —_ gettextposition 


Description 


Remarks 


Return Value 


Compatibility 


See Also 


Example 


_ gettextposition 


Gets the current text position. 
#include <graph.h> 


struct _rccoord __far _ gettextposition( void ); 


The _ gettextposition function returns the current text position as an _rccoord 
structure, defined in GRAPH.H. 


The _recoord structure contains the following elements: 


Element Description 
short row Row coordinate 
short col Column coordinate 


The text position given by the coordinates (1,1) is defined as the upper-left corner 
of the text window. 


Text output from the _ outtext and _outmem functions begins at the current text 
position. Font text is not affected by the current text position. Font text output 
begins at the current graphics output position, which is a separate position. Use the 
_moveto function to set the graphics output position. 


None. 


Standards: None 
16-Bit: DOS 
32-Bit: None 


_getcurrentposition functions, _moveto functions, _outmem, _outtext, 
_Settextposition, _settextwindow, _ wrapon 


/* QUTTXT.C: This example illustrates text output functions: 
_gettextcolor _getbkcolor  -_gettextposition _outtext 
_settextcolor  _setbkcolor -_settextposition 


_ gettextposition 


4Ainclude <conio.h> 
d#Finclude <stdio.h> 
#Hinclude <graph.h> 


char buffer [80]; 


void main( void ) 
{ 
/* Save original foreground, background, and text position. */ 
short blink, fgd, oldfgd; 
long bgd, oldbgd; 
Struct _rccoord oldpos; 


/* Save original foreground, background, and text position. */ 
oldfgd = _gettextcolor(); 

oldbgd = _getbkcolor(); 

oldpos = _gettextposition(); 

_clearscreen( _GCLEARSCREEN ); 


/* First time no blink, second time blinking. */ 
for( blink = @; blink <= 16; blink += 16 ) 


{ 
/* Loop through 8 background colors. */ 
for( bgd = @; bgd < 8; bgd++ ) 
{ 
_setbkcolor( bgd ); 
_settextposition( (short)bgd + ((blink / 16) * 9) + 3, 1 ); 
_settextcolor( 7 ); 
sprintf(buffer, "Back: %d Fore:", bgd ); 
_outtext( buffer ); 
/* Loop through 16 foreground colors. */ 
for( fgd = 0; fgd < 16; fgdt++ ) 
{ 
_settextcolor( fgd + blink ); 
sprintf( buffer, " 42d ", fgd + blink ); 
_outtext( buffer ); 
} 
} 
} 
_getch(); 


/* Restore original foreground, background, and text position. */ 
_settextcolor( oldfgd ); : 
_setbkcolor( oldbgd ); 
_clearscreen( _GCLEARSCREEN ); 
_settextposition( oldpos.row, oldpos.col ); 
} 
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382 _ gettextwindow 


Description 


Remarks 


Return Value 


Compatibility 


See Also 


Example 


_ gettextwindow 


Gets the boundaries of the current text window. 
#include <graph.h> 


void __far _ gettextwindow( short __ far *r/, short __ far *c/, 
short __ far *r2, short __far *c2 ); 


rl Top row of current text window 

cl Leftmost column of current text window 
r2 Bottom row of current text window 

c2 | Rightmost column of current text window 


The _ gettextwindow function finds the boundaries of the current text window. 
The text window is the region of the screen to which output from the _ outtext and 
_outmem functions is limited. By default, this is the entire screen, unless it has 
been redefined by the _ settextwindow function. 


The window defined by _settextwindow has no effect on output from the 
_ outgtext function. Text displayed with _ outgtext is limited to the current 
viewport. 


None. 


Standards: None 
16-Bit: DOS 
32-Bit: None 


_gettextposition, _outmem, _outtext, _scrolltextwindow, _settextposition, 
_settextwindow, _ wrapon 


See the example for _scrolltextwindow. 


Description 


Remarks 
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_ getvideoconfig 


Gets graphics video configuration information. 
#include <graph.h> 


struct _ videoconfig __ far * __ far _ getvideoconfig( struct _ videoconfig 
__far “config ); 


config Configuration information 


The _ getvideoconfig function returns the current graphics environment configura- 
tion in a_videoconfig structure, defined in GRAPH.H. 


The values returned reflect the currently active video adapter and monitor, as well 


as the current video mode. 


The _ videoconfig structure contains the following members, each of which is of 


type short: 

Member Contents 

numxpixels Number of pixels on the x axis 
numypixels Number of pixels on the y axis 
numtextcols Number of text columns available 
numtextrows Number of text rows available 
numcolors Number of color indices 
bitsperpixel Number of bits per pixel 
numvideopages Number of available video pages 
adapter Active display adapter 

mode Current video mode 

monitor Active display monitor 

memory Adapter video memory in kilobytes 


—384~—S _ getvideoconfig 


Return Value 


The values for the adapter member of the _ videoconfig structure are given by the 
manifest constants shown in the list below. For any applicable adapter (_CGA, 
_EGA, or __ VGA), the corresponding Olivetti adapter (_ OCGA, _OEGA, or 
_OVGA) represents a superset of graphics capabilities. 


Adapter Constant Meaning 

_CGA Color Graphics Adapter 

_EGA Enhanced Graphics Adapter 

_HGC Hercules Graphics Card 

_MCGA Multicolor Graphics Array 

—~MDPA Monochrome Display Printer Adapter 
OCGA Olivetti (AT&T) Color Graphics Adapter 
_OEGA Olivetti (AT&T) Enhanced Graphics Adapter 
_~OVGA Olivetti (AT&T) Video Graphics Array 
_VGA Video Graphics Array 

_SVGA Super Video Graphics Array (VESA) 


The values for the monitor member of the _ videoconfig structure are given by 
the manifest constants listed below: 


Monitor Constant Meaning 

_ANALOG Analog monochrome and color 

_ANALOGCOLOR Analog color only 

_ANALOGMONO Analog monochrome only 

_COLOR Color (or enhanced monitor emulating a color monitor) 
_ENHCOLOR Enhanced color 

_MONO Monochrome monitor 


In every text mode, including monochrome, the _ getvideoconfig function returns 
the value 32 for the number of available colors. The value 32 indicates the range 
of values (O—31) accepted by the _ settextcolor function. This includes 16 normal 
colors (O—15) and 16 blinking colors (16-31). Blinking is selected by adding 16 to 
the normal color index. Because monochrome text mode has fewer unique display 
attributes, some color indices are redundant. However, because blinking is 
selected in the same manner, monochrome text mode has the same range (0-31) 
as other text modes. 


The _ getvideoconfig function returns the video configuration information in a 
structure, as noted above. There is no error return. 


Compatibility 


See Also 


Example 


Output 


Standards: 
16-Bit: 
32-Bit: 


None 
DOS 


None 


_setvideomode, _setvideomoderows 


_ getvideoconfig 


/* GVIDCFG.C: This program displays information about the current 
* video configuration. 


* / 


#Hinclude <stdio.h> 
#Hinclude <graph.h> 


n( void ) 


struct _videoconfig vc; 


void mai 
{ 
short 
char 


C; 
b[50Q]; 


_getvideoconfig( &vc ); 


/* Write all 
c = sprintf( 
c += sprintf ( 
c += sprintf ( 
c t= sprintf ( 
c += sprintf ( 
Cute -Sprintt( 
C-+=Sprinve( 
es] Sprintt¢ 
c += sprintf ( 
c += sprintf ( 
c += sprintf ( 
_outtext( b ); 
} 
X pixels: Q 
Y pixels: Q 
Text columns: 8@ 
Text rows: 25 
Colors: Ys 


Bits/pixel: Q 
Video pages: 1 


Mode: 
Adapter: 
Monitor: 
Memory: 


256 


ion 


‘ 


oouvovUvU oO CUpU OO oD 


+++etetetrest 
NNN ANANaANANAN 


. ~ . ~“ w 7) ] we 


~“ 


"X pixels: 

"Y pixels: 
"Text columns: 
"Text rows: 
“Colors: 
"Bits/pixel: 
"Video pages: 
"Mode: 
"Adapter: 
"Monitor: 
“Memory: 


/* Buffer for string */ 


information to a string, then 


“d\n", 
“d\n", 
d\n", 
md\n", 
~d\n", 
d\n", 
“d\n", 
wd\n", 
d\n", 
~d\n", 
~d\n", 


output string. */ 


Ve; 
VC. 
.numtextcols ); 


vc 


vc. 
vc. 
.bitsperpixel ); 


vc 


VC. 
.mode ); 

.adapter ); 
.monitor ); 
.memory ); 


numxpixels ); 
numypixels ); 


numtextrows ); 
numcolors ); 


numvideopages ); 
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386 _ getviewcoord Functions 


Description 


Remarks 


Return Value 


_ getviewcoord Functions 


Translate coordinates to view coordinates. 
#include <graph.h> 


struct _xycoord __far _ getviewcoord( short x, short y ); 
struct _xycoord __far _ getviewcoord_w( double wx, double wy ); 


struct _xycoord __ far _ getviewcoord_wxy( struct _ wxycoord 
__far *pwxyl ); 


x,y Physical point to translate 
wx, wy Window point to translate 
pwxyl Window point to translate 


The _ getviewcoord routines translate the specified coordinates (x, y) from one 
coordinate system to view coordinates and then return them in an _ xycoord struc- 
ture, defined in GRAPH.H. The _ xycoord structure contains the following 
elements: 


Element Description 
short xcoord x coordinate 
short ycoord y coordinate 


The various _ getviewcoord routines translate in the following manner: 


Routine Translation 

_ getviewcoord Physical coordinates (x, y) to view coordinates 

_ getviewcoord_w Window coordinates (wx, wy) to view coordinates 

_ getviewcoord_ wxy Window coordinates structure (pwxy/) to view 
coordinates 


In Microsoft C version 5.1, the function _ getviewcoord was called _getlogcoord. 


The _ getviewcoord function returns the coordinates as noted above. There is no 
error return. 


Compatibility 


See Also 


Example 


_ getviewcoord Functions 


Standards: None 
16-Bit: DOS 
32-Bit: None 


_getphyscoord, _getwindowcoord, _ grstatus 


See the example for _setwindow. 


387 


388  _ getvisualpage 


Description 


Remarks 


Return Value 


Compatibility 


See Also 


Example 


_ getvisualpage 


Gets the current visual page number. 
#include <graph.h> 


short __ far _ getvisualpage( void ); 


The _ getvisualpage function returns the current visual page number. 


The function returns the number of the current visual page. All hardware combina- 
tions support at least one page (page number 0). 


Standards: None 
16-Bit: DOS 
32-Bit: None 


_getactivepage, _gettextcolor, _ gettextposition, _outtext, _setactivepage, 
_settextcolor, _settextposition, _settextwindow, _setvideomode, 
_setvisualpage, _wrapon 


See the example for _ getactivepage. 
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_ getw 


Description Gets an integer from a stream. 
#include <stdio.h> 
int _ getw( FILE *stream ); 


stream Pointer to FILE structure 


Remarks The _ getw function reads the next binary value of type int from the file associated 
with stream and increments the associated file pointer (if there is one) to point to 
the next unread character. The _ getw function does not assume any special align- 
ment of items in the stream. 


Return Value The _ getw function returns the integer value read. A return value of EOF may 
indicate an error or end-of-file. However, since the EOF value is also a legitimate 
integer value, feof or ferror should be used to verify an end-of-file or error 


condition. 

Compatibility Standards: UNIX 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 


Use _ getw for compatibility with ANSI naming conventions of non-ANSI func- 
tions. Use getw and link with OLDNAMES.LIB for UNIX compatibility. 


The _ getw function is provided primarily for compatibility with previous librar- 


ies. Note that portability problems may occur with _ getw, since the size of the int 
type and the ordering of bytes within the int type differ across systems. 


See Also _putw 
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Example /* GETW.C: This program uses _getw to read a word from a stream, 
* then performs an error check. 
* / 


dEinclude <stdio.h> 
d#Hinclude <stdlib.h> 


void main( void ) 


{ 
FILE *stream; 
int i; 
if( (stream = fopen( "_getw.c", "rb" )) == NULL ) 
printf( "Couldn't open file\n" ); 
else 
{ 
/* Read a word from the stream: */ 
i = _getw( stream ); 
/* If there is an error... */ 
if( ferror( stream ) ) 
{ 
printf( "_getw failed\n" ); 
clearerr( stream ); 
} 
else 
printf( “First data word in file: @x%.4x\n", i ); 
fclose( stream ); 
} 
_— 


Output First data word in file: Qx2a2f 


Description 


Remarks 


Return Value 


Compatibility 


See Also 


Example 
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_ getwindowcoord 
Translates view coordinates to window coordinates. 
#include <graph.h> 
struct _wxycoord __ far _ getwindowcoord( short x, short y ); 


x,y Viewport coordinate to translate 


The _ getwindowcoord function translates the view coordinates (x, y) to window 
coordinates and returns them in the _ wxycoord structure, defined in GRAPH.H. 


The _ wxycoord structure contains the following elements: 


Element Description 
double wx x coordinate 
double wy y coordinate 


The function returns the coordinates in the _ wxycoord structure. There is no error 
return. 


Standards: None 
16-Bit: DOS 
32-Bit: None 


_getphyscoord, _ getviewcoord functions, _moveto functions, _setwindow 


See the example for _setwindow. 
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_ getwritemode 


Description Gets the current logical mode for line drawing. 
#include <graph.h> 


short __ far _ getwritemode( void ); 


Remarks The _ getwritemode function returns the current logical write mode, which is used 
when drawing lines with the _lineto, _ polygon, and _ rectangle functions. 


The default value is _GPSET, which causes lines to be drawn in the current 
graphics color. The other possible return values are GXOR, _GAND, _GOR, 
and _GPRESET. See _ putimage for more details on these manifest constants. 


Return Value The _ getwritemode function returns the current logical write mode, or —1 if not in 
graphics mode. 


Compatibility Standards: None 
16-Bit: DOS 
32-Bit: None 
See Also _grstatus, _lineto functions, _ putimage functions, _ rectangle functions, 


_setcolor, _setlinestyle, _setwritemode 


Example /* GWRMODE.C: This program illustrates _getwritemode and _setwritemode. */ 


d#Ainclude <conio.h> 
d#Finclude <stdlib.h> 
##include <graph.h> 


short wmodes[5] 
char *wmstr[5] 


{ _GPSET, _GPRESET, _GXOR, _GOR, _GAND ie 
{ "PSET as "PRESET", "XOR uy "OR aa "AND we }3 


void box( short x, short y, short size, short writemode, short fillmode ); 


void main( void ) 


{ 


i 


void box( short x, short y, short size, short writemode, short fillmode ) 


{ 


Short i, X, Yy; 


/* Find a valid graphics mode. */ 


_ getwritemode 


if( !_setvideomode( _MAXCOLORMODE ) ) 


exit( 1 ); 


x = y = /0; 


box( x, y, 5@, _GPSET, _GFILLINTERIOR ); 


setcolor( 2 ); 


box( x, y, 40, _GPSET, _GFILLINTERIOR ); 


for( i= 0; i < 5; i++ ) 

{ 
_settextposition( 1, 1 ); 
_outtext( wmstr{[i] ); 


box( x t= 12, y += 12, 50, wmodes[i], _GBORDER ); 


_getch(); 
} 
_setvideomode( _DEFAULTMODE ); 
exit( @ ); 


short wm, side; 


wm = _getwritemode(); 
_setwritemode( writemode ); 


/* Save write mode and set new. */ 


_rectangle( fillmode, x - size, y - size, x + size, y + size ); 


_setwritemode( wm ); 


/* Restore original write mode. */ 
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Description 


Remarks 


gmtime 


Converts a time value to a structure. 
#include <time.h> 
struct tm *gmtime( const time_t *time ); 


timer Pointer to stored time 


The gmtime function converts the timer value to a structure. The timer argument 
represents the seconds elapsed since midnight (00:00:00), December 31, 1899, 
Universal Coordinated Time. This value is usually obtained from a call to the time 
function. 


The gmtime function breaks down the timer value and stores it in a structure of 
type tm, defined in TIME.H. The structure result reflects Universal Coordinated 
Time, not local time. 


The fields of the structure type tm store the following values, each of which is 
an int: 


Field Value Stored 

tm_sec Seconds 

tm_min Minutes 

tm_hour Hours (0-24) 

tm_mday Day of month (1-31) 

tm_mon Month (O—11; January = 0) 
tm_year Year (current year minus 1900) 
tm_wday Day of week (0-6; Sunday = 0) 
tm_yday Day of year (0-365; January 1 = 0) 
tm_isdst Always 0 for gmtime 


The gmtime, mktime, and localtime functions use a single statically allocated 
structure to hold the result. Each call to one of these routines destroys the result of 
any previous call. 


If timer represents a date before midnight, December 31, 1899, gmtime returns 
NULL. 
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Return Value The gmtime function returns a pointer to the structure result. There 1s no error 
return. 

Compatibility Standards: ANSI, UNIX 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 

See Also asctime, ctime, _ ftime, localtime, time 


Example /* GMTIME.C: This program uses gmtime to convert a long-integer 
* representation of Universal Coordinated Time to a structure named newtime, 
* then uses asctime to convert this structure to an output string. 
a / 


dAinclude <time.h> 
d#Hinclude <stdio.h> 


void main( void ) 


struct tm *newtime; 

long Itime; 

time( &ltime ); 

/* Obtain Universal Coordinated Time: */ 

newtime = gmtime( &ltime ); 

printf( "Universal Coordinated Time is %s\n", asctime( newtime ) ); 
} 


Output Universal Coordinated Time is Wed Jun 16 16:37:53 1999 
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Description 


Remarks 


_grstatus 


Returns the status of the most recent graphics function call. 


#include <graph.h> 


short __ far _ grstatus( void ); 


The _ grstatus function returns the status of the most recently used graphics func- 
tion. The _ grstatus function can be used immediately following a call to a 
graphics routine to determine if errors or warnings were generated. Return values 
less than 0 are errors, and values greater than 0 are warnings. 


The following manifest constants are defined in the GRAPH.H header file for use 
with the _ grstatus function: 


Value 


—] 
—2 


—3 


4 
5 
6 
as 
-8 


NO — 


Constant 


_GROK 
_GRERROR 
_~GRMODENOTSUPPORTED 


_GRNOTINPROPERMODE 


_GRINVALIDPA RA METER 
—_GRFONTFILENOTFOUND 
_GRINVALIDFONTFILE 
_~GRCORRUPTEDFONTFILE 
_GRINSUFFICIENTMEMORY 


_GRINVALIDIMAGEBUFFER 
—_GRNOOUTPUT 
_GRCLIPPED 
_~GRPARAMETERALTERED 


Meaning 


Success. 
Graphics error. 


Requested video mode not 
supported. 


Requested routine only works in 
certain video modes. 


One or more parameters invalid. 
No matching font file found. 

One or more font files invalid. 
One or more font files inconsistent. 
Not enough memory to allocate 
buffer or to complete a _ floodfill 
operation. 

Image buffer data inconsistent. 
Nothing drawn. 

Output was clipped to viewport. 
One or more input parameters was 
altered to be within range, or pairs 


of parameters were interchanged to 
be in the proper order. 
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After a graphics call, use an if statement to compare the return value of _ grstatus 
to __GROK. For example: 


if( _grstatus < _GROK ) 
/*handle graphics error*/ ; 


The functions listed below cannot cause errors, and they all set _grstatus to 


_GROK: 

_ displaycursor _ gettextposition _outtext 

_ getactivepage _ gettextwindow _unregisterfonts 
_getbkcolor _ getvideoconfig _Wwrapon 

_ getgtextvector _ getvisualpage 

_ gettextcolor _outmem 


See the list below for the graphics functions that affect _grstatus. The list shows 
error or warning messages that can be set by the graphics function. In addition to 
the error codes listed, any of these functions can produce the _GRERROR error 


code. 

Possible _ grstatus Possible _ grstatus 

Function Error Codes Warning Codes 

_are functions _GRNOTINPROPERMODE, _GRNOOUTPUT, 
—_GRINVALIDPARAMETER _GRCLIPPED 

_clearscreen _GRNOTINPROPERMODE, 
_GRINVALIDPARAMETER 

_ ellipse functions _GRNOTINPROPERMODE, _GRNOOUTPUT, 
_GRINVALIDPARAMETER, _GRCLIPPED 
_GRINSUFFICIENTMEMORY 

_floodfill functions _GRNOTINPROPERMODE, —_GRNOOUTPUT 
_GRINVALIDPARA METER, 
_GRINSUFFICIENTMEMORY 

_getarcinfo _GRNOTINPROPERMODE 

_getcurrentposition _GRNOTINPROPERMODE 

functions 

_ getfontinfo (_GRERROR only) 

_getgtextextent (_GRERROR only) 

_ getgtextvector —_GRPARAMETERALTERED 

_getimage functions _GRNOTINPROPERMODE _GRPARAMETERALTERED 

_getphyscoord _GRNOTINPROPERMODE 

_ getpixel functions _GRNOTINPROPERMODE 

_gettextcursor _GRNOTINPROPERMODE 


_getviewcoord functions —~GRNOTINPROPERMODE 
_getwindowcoord _GRNOTINPROPERMODE 
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Possible _ grstatus Possible _ grstatus 

Function Error Codes Warning Codes 

_ getwritemode _GRNOTINPROPERMODE 

_imagesize functions _GRNOTINPROPERMODE 

_lineto functions _GRNOTINPROPERMODE _GRNOOUTPUT, 

_GRCLIPPED 
_moveto functions _GRNOTINPROPERMODE 
_outgtext _GRNOTINPROPERMODE _GRCLIPPED, 
—~GRNOOUTPUT 

_ pie functions _GRNOTINPROPERMODE, _GRNOOUTPUT, 
_GRINVALIDPARAMETER, _GRCLIPPED 
_GRINSUFFICIENTMEMORY 

_ polygon functions _GRNOTINPROPERMODE, _GRNOOUTPUT, 
_GRINVALIDPARAMETER, _GRCLIPPED 
_GRINSUFFICIENTMEMORY 

_ putimage functions _GRERROR, —_GRPARAMETERALTERED, 
_GRNOTINPROPERMODE, —_GRNOOUTPUT 
_GRINVALIDPARAMETER, 
_GRINVALIDIMAGEBUFFER 

_rectangle functions _GRNOTINPROPERMODE, _GRNOOUTPUT, 
—_GRINVALIDPARAMETER, _GRCLIPPED 
_GRINSUFFICIENTMEMORY 

_registerfonts _~GRCORRUPTEDFONTFILE, 
_GRFONTFILENOTFOUND, 
_GRINSUFFICIENTMEMORY, 
_GRINVALIDFONTFILE 

_remappalette _GRERROR, 
_GRINVALIDPARAMETER 

_remapallpalette _GRERROR, 
_GRINVALIDPARAMETER 

_scrolltextwindow _~GRNOOUTPUT 

_Selectpalette _GRNOTINPROPERMODE, 
_GRINVALIDPARAMETER 

_ Setactivepage _GRINVALIDPARAMETER 

_setbkcolor _~GRINVALIDPARAMETER _GRPA RAMETERALTERED 

_setcliprgn _GRNOTINPROPERMODE _GRPARAMETERALTERED 

_setcolor _GRNOTINPROPERMODE _GRPARAMETERALTERED 

_setfont _GRERROR, | 
_GRFONTFILENOTFOUND, 
_GRINSUFFICIENTMEMORY, 
_GRPARAMETERALTERED 

_setgtextvector _GRPARAMETERALTERED 


_Setpixel _GRNOTINPROPERMODE —~GRNOOUTPUT 


Function 


_settextcolor 
_settextcursor 


_Settextposition 


_ settextrows 


_settextwindow 


_setvideomode 


_setvideomoderows 


_setvieworg 
_setviewport 
_setvisualpage 
_setwindow 


_setwritemode 


Return Value 


See Also 


Compatibility 


Possible _ grstatus 
Error Codes 


_GRNOTINPROPERMODE 


_GRINVALIDPA RAMETER 


_GRERROR, 
_GRMODENOTSUPPORTED, 
_GRINVALIDPARAMETER 


_GRERROR, 
_GRMODENOTSUPPORTED, 
_GRINVALIDPARAMETER 


_GRNOTINPROPERMODE 
_GRNOTINPROPERMODE 
—~GRINVALIDPA RAMETER 


_~GRNOTINPROPERMODE, 
_~GRINVALIDPARAMETER 


—_GRNOTINPROPERMODE, 
_GRINVALIDPA RAMETER 
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Possible _ grstatus 
Warning Codes 


_GRPARAMETERALTERED 
_GRPARAMETERALTERED 


_~GRPARAMETERALTERED 
_~GRPARAMETERALTERED 


_GRPARAMETERALTERED 


_GRPARAMETERALTERED 


The _ grstatus function returns the status of the most recently used graphics 


function. 


_arc functions, _ ellipse functions, _floodfill functions, —lineto functions, 


_pie functions, _remapallpalette, _setactivepage, _setbkcolor, _setcolor, 


_setpixel functions, _settextcolor, _settextcursor, _setvisualpage, 
_setwindow, _setwritemode 


Standards: 


16-Bit: 
32-Bit: 


None 
DOS 


None 
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Description 


Remarks 


Return Value 


Compatibility 


See Also 


_halloe 


Allocates a huge memory block. 
#include <malloc.h> Required only for function declarations 
void __ huge *_halloc( long num, size_t size ); 


num Number of elements 


size Length in bytes of each element 


The _halloc function allocates a huge array from the operating system consisting 
of num elements, each of which is size bytes long. Each element is initialized to 0. 
If the size of the array is greater than 128K (131,072 bytes), the size of an array 
element must then be a power of 2. 


Use the _hfree function to deallocate a block of memory returned by halloc. 


The _halloc function returns a void huge pointer to the allocated space, which is 
guaranteed to be suitably aligned for storage of any type of object. To get a pointer 
to a type other than void huge, use a type cast on the return value. If the request 
cannot be satisfied, the return value is NULL. 


Standards: None 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: None 


calloc functions, free functions, _hfree, malloc functions 


—_halloc 401 


Example /* HALLOC.C: This program uses _halloc to allocate space for 30,000 long 
* integers, then uses _hfree to deallocate the memory. 
* / 
#Hinclude <stdio.h> 
#Finclude <stdlib.h> 
#FHinclude <malloc.h> 


void main( void ) 


{ 
long __huge *hbuf; 
/* Allocate huge buffer */ 
hbuf = (long __huge *)_halloc( 3@@00L, sizeof( long ) ); 
if ¢€ hbuf == NULL ) 
printf( “Insufficient memory available\n" ); 
else 
printf( "Memory successfully allocated\n" ); 
/* Free huge buffer */ 
_hfree( hbuf ); 
} 


Output Memory successfully allocated 


402 _ hard Functions 


Description 


Remarks 


_ hard Functions 


Handle critical error conditions. 
#include <dos.h> 


void _harderr( void( __ far *handler )( )); 
void _hardresume( int result ); 


void _hardretn( int error ); 


handler () New INT 0x24 handler 
result Handler return parameter 
error Error to return from 


These three functions are used to handle critical error conditions that use DOS in- 
terrupt 0x24. The _harderr function installs a new critical-error handler for inter- 
rupt 0x24. 


When a critical error occurs, control is passed to the function specified in the 
_harderr call. The _hardresume and _ hardretn functions control how the pro- 
gram will return from the critical error handler. 


The _hardresume function returns to DOS the code that encountered the critical 
error. 


The _hardretn function returns directly to the application program that issued the 
INT 0x21 DOS system call, which, in turn, encountered the critical error. 


The _harderr function does not directly install the handler pointed to by handler; 
instead, _ harderr installs a handler that calls the function referenced by handler. 
The handler calls the function with the following parameters: 


handler(unsigned deverror, unsigned errcode, unsigned __ far *devhdr); 


_ The deverror argument is the device error code. It contains the AX register value 


passed by DOS to the INT 0x24 handler. The errcode argument is the DI register 
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value that DOS passes to the handler. The low-order byte of errcode can be one of 
the following values: 


OQ 
cm) 
oF 
o 


SANA nN hk WON = S&S 


Meaning 


Attempt to write to a write-protected disk 
Unknown unit 

Drive not ready 

Unknown command 
Cyclic-redundancy-check error in data 
Bad drive-request structure length 
Seek error 

Unknown media type 

Sector not found 

Printer out of paper 

Write fault 

Read fault 

General failure 


The devhdr argument is a far pointer to a device header that contains descriptive 
information about the device on which the error occurred. The user-defined han- 
dler must not change the information in the device-header control block. 


Errors on Disk Devices 


If the error occurred on a disk device, the high-order bit (bit 15) of the deverror 
argument will be set to 0, and the deverror argument will indicate the following: 


Bit 
15 
14 
13 
12 
11 


10,9 


Meaning 


Disk error if false (0). 

Not used. 

“Ignore” response not allowed if false (0). 
“Retry” response not allowed if false (0). 


“Fail” response not allowed if false (0). Note that DOS changes “fail” 
to “abort”. 


Code Location 

00 DOS 

01 File allocation table 
10 Directory 

11 Data area 


Read error if false; write error if true. 


404 
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The low-order byte of deverror indicates the drive in which the error occurred (O = 
drive A, 1 = drive B, etc.). 


Errors on Other Devices 

If the error occurs on a device other than a disk drive, the high-order bit (bit 15) of 
the deverror argument is 1. The attribute word located at offset 4 in the device- 
header block indicates the type of device that had the error. If bit 15 of the at- 
tribute word is 0, the error is a bad memory image of the file allocation table. If 
the bit is 1, the error occurred on a character device and bits O—3 of the attribute 
word indicate the type of device, as shown in the following list: 


Bit Meaning 

0 Current standard input 
1 Current standard output 
Z Current null device 

3 Current clock device 


Restrictions on Handler Functions 


The user-defined handler function can issue only system calls 0x01 through Ox0C, 
or 0x59. Thus, many of the standard C run-time functions (such as the I/O and 
_heap functions) cannot be used in a hardware error handler. System call 0x59 
can be used to obtain further information about the error that occurred. 


Using _hardresume and _ harderr 

If the handler returns, it can do so in several different ways: 
= Via the return statement 

= By calling the _hardresume function 

= By calling the _hardretn function 


If the handler returns from _hardresume or from a return statement, control 
returns to DOS. 


The _hardresume function should be called only from within the user-defined 
hardware error-handler function. The result supplied to _hardresume must be one 
of the following constants: 


Constant Action | 
_HARDERR_ ABORT Aborts the program by issuing INT 0x24 
—HARDERR_ FAIL Fails the system call that is in progress (this is not 


supported on DOS 2.x) 
_HARDERR_ IGNORE Ignores the error 
_HARDERR_ RETRY Retries the operation 


Return Value 


Compatibility 


See Also 
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The _ hardretn function allows the user-defined hardware error handler to return 
directly to the application program rather than returning to DOS. The application 
resumes at the point just after the failing I/O function request. The _ hardretn 
function should be called only from within a user-defined hardware error-handler 
function. 


The error parameter of _hardretn should be a DOS error code, as opposed to the 
XENIX-style error code that is available in errno. Refer to MS-DOS Encyclopedia 
(Duncan, ed.; Redmond, Wa.: Microsoft Press, 1988) or Programmer’s PC 
Sourcebook 2nd ed. (Hogan; Redmond, Wa.: Microsoft Press, 1991) for informa- 
tion about the DOS error codes that may be returned by a given DOS function call. 


If the failing I/O function request is an INT 0x21 function greater than or equal to 
function 0x38, _ hardretn will then return to the application with the carry flag set 
and the AX register set to the _hardretn error parameter. If the failing INT 0x21 
function request is less than function 0x38 and the function can return an error, the 
AL register will be set to OxFF on return to the application. If the failing INT 0x21 
does not have a way of returning an error condition (which is true of certain INT 
0x21 functions below 0x38), the error parameter of _hardretn is not used, and no 
error code is returned to the application. 


None. 


Standards: None 
16-Bit: DOS 
32-Bit: None 


_chain_intr, _dos_getvect, _dos_setvect 
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Description 


Remarks 


Return Value 


Compatibility 


See Also 


_heapadd Functions 


Add memory to the heap (_heapadd) or to the based heap (_ bheapadd). 
#include <malloc.h> Required only for function declarations 


int _heapadd( void __ far *memblock, size_t size ); 


int _bheapadd( __ segment seg, void __ based (void) *memblock, size_t size ); 


seg Based-heap segment selector 
buffer Pointer to heap memory 
S1Ze Size in bytes of memory to add 


The _heapadd and _ bheapadd functions add an unused piece of memory to the 
heap. The _ bheapadd function adds the memory to the based heap specified by 
seg. The _heapadd function looks at the segment value and, if it is DGROUP, 
adds the memory to the near heap. Otherwise, _heapadd adds the memory to the 
far heap. 


These functions return O if successful, or —1 1f an error occurred. 


_ headadd 

Standards: None 

16-Bit: DOS 

32-Bit: DOS32X 

_ bheadadd 

Standards: None 

16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: None 


free functions, _halloc, _hfree, malloc functions, realloc functions 
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Example /* HEAPMIN.C: This program illustrates heap management using 
* heapadd and _heapmin. 
* / 


dEinclude <stdio.h> 
d#Hinclude <conio.h> 
#Hinclude <process.h> 
#Hinclude <malloc.h> 


void heapdump( char *msg ); /* Prototype */ 


char sl[] 
char s2[] 


{ "Here are some strings that we use at first, then don't\n" }; 
{ "need any more. We'll give their space to the heap.\n" }; 


void main( void ) 
{ 
Int: pls ly as 


DINE EG “ASS 5 -Si.. G2. 9 
heapdump( "Initial heap" ); 


/* Give space of used strings to heap. */ 


if ( _heapadd( sl, sizeof( sl )) == -1 ) 
printerc“Error. Nn"): 
if ( _heapadd( s2, sizeof( s2 )) == -1 ) 


printf("Error.\n"); 
heapdump( "After adding used strings” ); 


/* Allocate some blocks. Some may use string blocks from _heapadd. */ 
for( i = 0; 1 < 2; itt ) 
if( (pLi] = (int *)calloc( 10 * (i + 1), sizeof( int ) )) == NULL ) 
{ 
S| 
break; 
iE 
heapdump( "After allocating memory" ); 


/* Free some of the blocks. */ 
freee plil:33 

free( p[2] ); 

heapdump( "After freeing memory" ); 


/* Minimize heap. */ 
_heapmin(); 
heapdump( "After compacting heap" ); 
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/* Walk through heap entries, displaying information about each block. 


void heapdump( char *msg_ ) 
{ 
_HEAPINFO hi; 


printf( "%s\n", msg ); 


hi. _pentry = NULL; 
while( _heapwalk( &hi ) == _HEAPOK ) 
printf( "\t%s block at “Fp of size 4u\t\n", 
hi._useflag == _USEDENTRY ? "USED" : "FREE", 
hi. _pentry, 


hi._size ); 
printf("Press any key.\n"); 
_getch(); 


Here are some 
need any more. 
Initial heap 


USED block 
USED block 
USED block 
FREE block 


at 2D39:@E9C 
at 2D39:100A 
at 2D39:1030 
at 2D39:1232 


of 
of 
of 
of 


size 
size 
size 
size 


After adding used strings 


FREE 
FREE 
USED 
USED 
USED 
USED 
FREE 


block 
block 
block 
block 
block 
block 
block 


at 
at 
at 
at 
at 
at 
at 


After allocating 


USED 
USED 
FREE 
USED 
USED 
USED 
USED 
FREE 


block 
block 
block 
block 
block 
block 
block 
block 


After freeing 


USED 
FREE 
FREE 
USED 
USED 
USED 
USED 
FREE 


block 
block 
block 
block 
block 
block 
block 
block 


at 
at 
at 
at 


at 


at 
at 
at 


2D39: 
:QQ07A 


2D39 


2039: | 
:@E9C 
2039: 
2D39: 
2D39: 


2039 


0044 
QQAE 
100A 


1030 
1232 


memory 


2D39 


2D39 
2D39 
2D39 
2D39 


memory 


at 
at 
at 
at 
at 
at 
at 
at 


2D39 


2D39 
2D39 
2D39 


:0044 
2039: 


QQ5A 


:@084 
:Q@QAE 
:@E9C 
> 1Q0A 
2D39: 
2039: 


1030 
1232 


: 0044 
2039: 


QQ5A 


0084 
:@QAE 
:@E9C 
2D39: 
2D39: 
2039: 


100A 
1030 
1232 


of 
of 
of 
of 
of 
of 
of 


of 
of 
of 
of 
of 
of 
of 
of 


of 
of 
of 
of 
of 
of 
of 
of 


size 
size 
size 
size 
size 
size 
size 


size 
size 
size 
size 
size 
size 
size 
size 


size 
size 
size 
size 
size 
size 
size 
size 


strings that we use at first, then don't 
We'll give their space to the heap. 


364 
36 

512 
460 


* / 


After compacting 


USED 
FREE 
USED 
USED 
USED 
USED 
FREE 


block 
block 
block 
block 
block 
block 
block 


at 
at 
at 
at 
at 
at 
at 


heap 
2039 
2039 
2D39 
2039 


70044 
:@05A 
> @@AE 
:@E9C 
2D39: 
2039: 
2039: 


100A 
1030 
£232 


of 
of 
of 
of 
of 
of 
of 


size 
size 
size 
size 
size 
size 
size 
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_heapchk Functions 


Description Run consistency checks on the heap. 
#include <malloc.h> 


int _heapchk( void ); 
int _ bheapchk( __ segment seg ); 
int _fheapchk( void ); 


int _nheapchk( void ); 


seg Specified base heap 
Remarks The _heapchk routines help to debug heap-related problems by checking for mini- 
mal consistency of the heap. Each function checks a particular heap, as listed 
below: 
Function Heap Checked 
_heapchk Depends on data model of program 
_bheapchk Based heap specified by seg value 
_fheapchk Far heap (outside the default data segment) 
_nhheapchk Near heap (inside the default data segment) 


In large data models (that is, compact-, large-, and huge-model programs), 
_heapchk maps to _ fheapchk. In small data models (tiny-, small-, and medium- 
model programs), _heapchk maps to _nheapchk. 


For _heapchk, if the seg value is _NULLSKG, all based heap segments are 
checked; otherwise, only the specified one is checked. 


Return Value 


Compatibility 


See Also 


Example 
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All four routines return an integer value that is one of the following manifest con- 
stants (defined in MALLOC.H): 


Constant Meaning 

_HEAPBADBEGIN Initial header information cannot be found, or it is bad. 
_HEAPBADNODE Bad node has been found, or the heap is damaged. 
_HEAPEMPTY Heap has not been initialized. 

_HEAPOK Heap appears to be consistent. 

_heapchk 

Standards: None 

16-Bit: DOS 

32-Bit: DOS32X 


_bheapchk, _ fheapchk 
Standards: None 


16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: None 

_nheapchk 

Standards: None 

16-Bit: DOS 

32-Bit: None 


_heapset functions, _heapwalk functions 


/* HEAPCHK.C: This program checks the heap for consistency 
* and prints an appropriate message. 


4#Hinclude <malloc.h> 
d#Hinclude <stdio.h> 
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void main( void ) 


{ 
int heapstatus; 
char *buffer; 
/* Allocate and deallocate some memory */ 
if( (buffer = (char *)malloc( 100 )) != NULL ) 
free( buffer ); 
/* Check heap status */ 
heapstatus = _heapchk(); 
switch( heapstatus ) 
{ 
case _HEAPOK: 
printf(" OK - heap is fine\n" ); 
break; 
case _HEAPEMPTY: 
printf(" OK - heap is empty\n" ); 
break; 
case _HEAPBADBEGIN: 
printf( "ERROR - bad start of heap\n" ); 
break; 
case _HEAPBADNODE: 
— printf( "ERROR - bad node in heap\n" ); 
break; 
} 
} 


Output OK - heap is fine 
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_heapmin Functions 


Description Release unused heap memory to the operating system. 
#include <malloc. h> 


int _heapmin( void ); 
int _bheapmin( __ segment seg ) 
int _ fheapmin( void ); 


int _nheapmin( void ); 


seg Specified based-heap selector 


Remarks The _heapmin functions minimize the heap by releasing unused heap memory to 
the operating system. 


The various _ heapmin functions release unused memory in these heaps: 


Function Heap Minimized 

_heapmin Depends on data model of program. 

_bheapmin Based heap specified by seg value; _NULLSKG specifies all 
based heaps. 

_fheapmin Far heap (outside default data segment). 

_nheapmin Near heap (inside default data segment). 


In large data models (that is, compact-, large-, and huge-model programs), 
_heapmin maps to _fheapmin. In small data models (tiny-, small-, and medium- 
model programs), _ heapmin maps to _nheapmin. 


For _heapmin, if the supplied seg value is _NULLSKG, all based heap segments 
are minimized; otherwise, only the specified one is minimized. 


Based-heap segments are never freed (i.e., unlinked from the based heap list 
and released back to the operating system) by the _ bheapmin function. The 
_bfreeseg function is used for that purpose. 


Return Value The _ heapmin functions return 0 if the function completed successfully, or —1 in 
the case of an error. 
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Compatibility 


See Also 


_heapmin 

Standards: None 

16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 


_bheapmin, _ fheapmin, _ nheapmin 
Standards: None 

16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: None 


_bfreeseg, free functions, malloc functions 


Description 


Remarks 
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_heapset Functions 


Check heaps for minimal consistency and set the free entries to a specified value. 
#include <malloc.h> 


int _heapset( unsigned int fill ); 
int _bheapset( __ segment seg, unsigned int fill ); 
int _fheapset( unsigned int fill ); 


int _nheapset( unsigned int fill ); 


fill Fill character 


seg Specified based-heap segment selector 


The _heapset family of routines helps debug heap-related problems in programs 
by showing free memory locations or nodes unintentionally overwritten. 


The _heapset routines first check for minimal consistency on the heap in a man- 
ner identical to that of the _heapchk functions. In addition, the _ heapset func- 
tions set each byte of the heap’s free entries to the fill value. This known value 
shows which memory locations of the heap contain free nodes and which locations 
contain data that were unintentionally written to freed memory. 


The various _ heapset functions check and fill these heaps: 


Function Heap Filled 

_heapset Depends on data model of program. 

_bheapset Based heap specified by seg value; _NULLSEG specifies all 
based heaps. 

_fheapset Far heap (outside default data segment). 

_nheapset Near heap (inside default data segment). 


In large data models (that is, compact-, large-, and huge-model programs), 
_heapset maps to _fheapset. In small data models (tiny-, small-, and medium- 
model programs), _ heapset maps to _nheapset. 


For _heapset, if the seg value is _NULLSKG, all based heap segments are 
checked; otherwise, only the specified one is checked. 
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Return Value 


Compatibility 


See Also 


Example 


All four routines return an int whose value is one of the following manifest con- 
stants (defined in MALLOC.H): 


Constant Meaning 

_HEAPBADBEGIN Initial header information cannot be found, or it is 
invalid. 

_HEAPBADNODE Bad node has been found, or the heap is damaged. 

_HEAPEMPTY Heap has not been initialized. 

_HEAPOK Heap appears to be consistent. 

_heapset 

Standards: None 

16-Bit: DOS 

32-Bit: DOS32X 


_bheapset, _ fheapset 
Standards: None 


16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: None 
_nheapset 


Standards: None 
16-Bit: DOS 


— 32-Bit: None 


_heapchk functions, _ heapwalk functions 


/* HEAPSET.C: This program checks the heap and fills in free entries 
* with the character 'Z'. 


dFinclude <malloc.h> 
d#Finclude <stdio.h> 
#Hinclude <stdlib.h> 
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void main( void ) 
{ 
int heapstatus; 
char *buffer; 


if( (buffer = malloc( 1 )) == NULL ) /* Make sure heap is initialized */ 
exit( @ ); 
heapstatus = _heapset( ‘'Z' ); /* Fill in free entries */ 
switch( heapstatus ) 
{ 
case _HEAPOK: 
printf( "OK - heap is fine\n" ); 
break; 
case _HEAPEMPTY: 
printf( "OK - heap is empty\n" ); 
break; | 
case _HEAPBADBEGIN: 
printf( "ERROR - bad start of heap\n" ); 
break; 
case _HEAPBADNODE: 
printf( "ERROR - bad node in heap\n" ); 
break; 
} 
free( buffer ); 


Output OK - heap is fine 
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Description 


Remarks 


_ heapwalk Functions 


Traverse the heap and return information about the next entry. 
include <malloc.h> 


int _heapwalk( _HEAPINFO “entryinfo ); 

int _bheapwalk( ___ segment seg, _HEAPINFO *entryinfo ); 
int _fheapwalk( _HEAPINFO “entryinfo ); 

int _nheapwalk( _HEAPINFO “entryinfo); 


entryinfo Buffer to contain heap information 


seg Based-heap segment selector 


The _heapwalk family of routines helps debug heap-related problems in 
programs. 


The _heapwalk routines walk through the heap, traversing one entry per call, and 
return a pointer to a structure of type _HEAPINFO that contains information 
about the next heap entry. The _.HEAPINFO type, defined in MALLOC.H, con- 
tains the following elements: 


Element Description 

int far *_ pentry Heap entry pointer 
size_t _size Size of heap entry 

int _useflag Entry “in use” flag 


A call to _heapwalk that returns _HEAPOK stores the size of the entry in 

the _ size field and sets the _ useflag field to either _FREEENTRY or 
_USEDENTRY (both are constants defined in MALLOC.H). To obtain this infor- 
mation about the first entry in the heap, pass the _ heapwalk routine a pointer to a 
—HEAPINFO structure whose _ pentry member is NULL. 


Return Value 


Compatibility 
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The various _ heapwalk functions walk through and gather information on these 


heaps: 

Function Heap Walked 

_heapwalk Depends on data model of program. 

_bheapwalk Based heap specified by seg value; _NULLSEG specifies all 
based heaps. 

_fheapwalk Far heap (outside default data segment). 

_nheapwalk Near heap (inside default data segment). 


In large data models (that is, compact-, large-, and huge-model programs), 
_heapwalk maps to _ fheapwalk. In small data models (tiny-, small-, and 
medium-model programs), _ heapwalk maps to _nheapwalk. 


For _heapwalk, if the seg value is .NULLSKEG, all based heap segments will be 


traversed; otherwise, only the specified based heap is walked. 


All three routines return one of the following manifest constants (defined in 
MALLOC.H): 


Constant Meaning 

_HEAPBADBEGIN The initial header information cannot be found, or it is 
invalid. 

_HEAPBADNODE A bad node has been found, or the heap is damaged. 

—_HEAPBADPTR The _ pentry field of the _HEAPINFO structure does not 
contain a valid pointer into the heap. 

_HEAPEND The end of the heap has been reached successfully. 

_HEAPEMPTY The heap has not been initialized. 

_HEAPOK No errors so far; the _HEAPINFO structure contains 


information about the next entry. 


_heapwalk 
Standards: None 
16-Bit: DOS 
32-Bit: DOS32X 


_ bheapwalk, _ fheapwalk 

Standards: None 

16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: None 
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_nheapwalk 


Standards: None 


16-Bit: DOS 
32-Bit: None 
See Also _heapchk functions, _ heapset functions 


Example /* HEAPWALK.C: This program "walks" the heap, starting at the beginning 
* (_pentry = NULL). It prints out each heap entry's use, location, 
* and size. It also prints out information about the overall state 

of the heap as soon as _heapwalk returns a value other than _HEAPOK. 


% 


* / 


dAinclude <stdio.h> 
dFinclude <malloc.h> 


void heapdump( void ); 


void main( void ) 
{ 
char «buffer; 


heapdump(); 
if( (buffer = malloc( 59 )) != NULL ) 
; | 
heapdump(); 
free( buffer ); 
} 
heapdump(); 
} 


void heapdump( void ) 
{ 
_HEAPINFO hinfo; 
int heapstatus; 


hinfo._pentry = NULL; 
while( ( heapstatus = _heapwalk( &hinfo ) ) == _HEAPOK ) 
{ 
printf( "%6s block at “Fp of size %44.4X\n", 
( hinfo._useflag == _USEDENTRY ? "USED" : "FREE" ), 
hinfo._pentry, hinfo._size ); | 


Output 


Sswitch( heapstatus ) 


printf( "OK - empty heap\n" ); 


printf( "OK - end of heap\n" ); 


{ 
case _HEAPEMPTY: 
break; 
case _HEAPEND: 
break; 
case _HEAPBADPTR: 
printf( "ERROR - 
break; 
case _HEAPBADBEGIN: 
printf( "ERROR - 
break; 
case _HEAPBADNODE: 
printf( "ERROR - 
break; 
} 


USED block at 0067: 
USED block at QQ67: 
USED block at 90067: 
USED block at 0Q67: 
FREE block at 0067: 


OK - end of heap 


USED block at QQ67: 
USED block at 0067: 
USED block at 0067: 
USED block at QQ6/7: 
USED block at 0067: 
FREE block at 067: 


OK - end of heap 


USED block at 067: 
USED block at 0067: 
USED block at Q@Q67: 
USED block at 0067: 
FREE block at 0067: 
FREE block at QQ6/7: 


OK - end of heap 


103E 
104E 
1244 
126C 
146E 


1Q3E 
1Q4E 
1244 
126C 
146E 
14AC 


103E 
104E 
1244 
126C 
146E 
14AC 
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bad pointer to heap\n" ); 


bad start of heap\n" ); 


bad node in heap\n" ); 
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0026 
0200 
Q03C 
QB52 
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422 _hfree 


Description 


Remarks 


Return Value 


Compatibility 


See Also 


_hfree 


Frees a huge memory block. 
#include <malloc.h> Required only for function declarations 
void _hfree( void __ huge *memblock ); 


memblock Pointer to allocated memory block 


The _hfree function deallocates a memory block; the freed memory is returned to 
the operating system. The memblock argument points to a memory block pre- 
viously allocated through a call to _halloc. The number of bytes freed is the num- 
ber of bytes specified when the block was allocated. 


Note that attempting to free an invalid memblock argument (one not allocated with 
_halloc) may affect subsequent allocation and cause errors. 


None. 


Standards: None 


16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: None 
_halloc 


Example /* HALLOC.C: This program uses _halloc to allocate space for 30,00 long 


* / 


* integers, then uses _hfree to deallocate the memory. 


dFinclude <stdio.h> 
#Finclude <stdlib.h> 
d#Hinclude <malloc.h> 
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void main( void ) 
{ 
long __huge *hbuf; 


/* Allocate huge buffer */ 
hbuf = (long __huge *) halloc( 30000L, sizeof( long ) ); 
if ( hbuf == NULL ) 
printf( "Insufficient memory available\n" ); 
else 
printf( "Memory successfully allocated\n" ); 


/* Free huge buffer */ 
_hfree( hbuf ); 


Output Memory successfully allocated 
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Description 


Remarks 


Return Value 


Compatibility 


See Also 


_hypot, _ hypotl 


Calculate the hypotenuse. 
#include <math.h> 


double _hypot( double x, double y ); 


long double _hypotl( long double x, long double y ); 


x,y Floating-point values 


The _hypot and _ hypotl functions calculate the length of the hypotenuse of a 
right triangle, given the length of the two sides x and y (or x/ and yl). A call to 
_hypot is equivalent to Vx" + y’. 


The —_ hypotl function uses the 80-bit, 10-byte coprocessor form of arguments and 
return values. See the reference page on the long double functions for more details 
on this data type. 


The functions return the length of the hypotenuse. If an overflow results, the func- 
tions return HUGE_ VAL and set errno to ERANGE. 


_hypot 

Standards: UNIX 

16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 


Use _hypot for compatibility with ANSI naming conventions of non-ANSI func- 
tions. Use hypot and link with OLDNAMES.LIB for UNIX compatibility. 


_hypotl 

Standards: None 

16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: None 


_cabs 


Example 


Output 


_hypot, _ hypotl 


/* HYPOT.C: This program prints the hypotenuse of a right triangle. */ 


#Ainclude <math.h> 
#FAinclude <stdio.h> 


void main( void ) 


1 
double x = 3.0; y = 4.0: 
printf( "If a right triangle has sides %42.1f and 42.1f, " 
"its hypotenuse is %42.1f\n", x, y, _hypot( x, y ) ); 
} 


If a right triangle has sides 3.0 and 4.0, its hypotenuse is 5.0 
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Description 


Remarks 


Return Value 


_imagesize Functions 


Get amount of memory required to store graphics images. 
#include <graph.h> 


long __ far _imagesize( short x/, short y/, short x2, short y2 ); 
long __far _imagesize_ w( double wx/, double wy/, double wx2, double wy2 ); 


long __ far _imagesize_ wxy( struct _ wxycoord __ far *pwxy/, 
struct _wxycoord __ far *pwxy2 ); 


xl, yl Upper-left corner of bounding rectangle 
X22 Lower-right corner of bounding rectangle 
wxl, wyl Upper-left corner of bounding rectangle 
wx2, wy2 Lower-right corner of bounding rectangle 
pwxyl Upper-left corner of bounding rectangle 
pwxy2 Lower-right corner of bounding rectangle 


The functions in the _imagesize family return the number of bytes needed to store 
the image defined by the bounding rectangle and specified by the coordinates 
given in the function call. 


The _ imagesize function defines the bounding rectangle in terms of view- 
coordinate points (x/, y/) and (x2, y2). 


The _imagesize_w function defines the bounding rectangle in terms of window- 
coordinate points (x/, y/) and (x2, y2). 


The _imagesize_wxy function defines the bounding rectangle in terms of the 
window-coordinate pairs pwxy/ and pwxy2. 


The function returns the storage size of the image in bytes. There is no error return. 


Compatibility 


See Also 


Example 


_imagesize Functions 


Standards: None 
16-Bit: DOS 
32-Bit: None 


_getimage functions, _ getvideoconfig, _ putimage functions 


See the example for _ getimage. 
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428 «6 _ inp, _ inpw 


Description 


Remarks 


Return Value 


Compatibility 


See Also 


Example 


_inp, _inpw 


Input a byte (_inp) or a word (_inpw) from a port. 
#include <conio.h> Required only for function declarations 


int _inp( unsigned port ); 


unsigned _inpw( unsigned port ); 


port Port number 


The _inp and _inpw functions read a byte and a word, respectively, from the 
specified input port. The input value can be any unsigned integer in the range 
0 — 65,535. 


The functions return the byte or word read from port. There is no error return. 


Standards: None 
16-Bit: DOS 
32-Bit: None 


_outp, _outpw 


See the example for _outp. 
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_ int86 
Description Executes an 8086 interrupt. 
#include <dos.h> 


int _int86( int intnum, union _REGS *inregs, union _REGS *outregs ); 


inthum Interrupt number 
inregs Register values on call 
outregs Register values on return 
Remarks The _int86 function executes the 8086-processor-family interrupt specified by the 


interrupt number intnum. Before executing the interrupt, _ int86 copies the con- 
tents of inregs to the corresponding registers. After the interrupt returns, the func- 
tion copies the current register values to outregs. It also copies the status of the 
system carry flag to the cflag field in the outregs argument. The inregs and 
outregs arguments are unions of type _ REGS. The union type is defined in the 
include file DOS.H. 


Do not use the _ int86 function to call interrupts that modify the DS register. In- 
stead, use the _int86x function. (The _int86x function loads the DS and ES regis- 
ters from the segregs parameter and also stores the DS and ES registers into 
segregs after the function call.) 


The _ REGS type is defined in the include file DOS.H. 


Return Value The return value is the value in the AX register after the interrupt returns. If the 
cflag field in outregs is nonzero, an error has occurred; in such cases, the 
_doserrno variable is also set to the corresponding error code. 


Compatibility Standards: None 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: None 


See Also _bdos, _ int86x, _intdos, _ intdosx 
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Example /* INT86.C: This program uses _int86 to call the BIOS video service 
* (INT 10H) to get information about the cursor. 
* / 


4#Ainclude <dos.h> 
d#Ainclude <stdio.h> 


void main( void ) 


{ 
union _REGS inregs, outregs; 


/* Set up to get cursor information. */ 
inregs.h.ah = 3; /* Get Cursor Position function */ 
inregs.h.bh Q; /* Page 0 */ 


/* Execute video interrupt: */ 
_int86( 0x10, &inregs, &outregs ); 


/* Display results. */ 

printf( "Cursor position\n\tRow: 4d\n\tColumn: %d\n", 
outregs.h.dh, outregs.h.dl ); 

printf( "Cursor shape\n\tStart: %d\n\tEnd: 4d\n", 
outregs.h.ch, outregs.h.cl ); 


Output Cursor position 
Row: 2 
Column: @ 
Cursor shape 
Start: 6 
End: 7 
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_ int86x 
Description Executes an 8086 interrupt; accepts segment-register values. 
#include <dos.h> 


int _int86x( int intnum, union _REGS *inregs, union _REGS “*outregs, 
struct _SREGS *segregs ); 


inthum Interrupt number 
inregs Register values on call 
outregs Register values on return 
Segregs Segment-register values on call 
Remarks The _ int86x function executes the 8086-processor-family interrupt specified by 


the interrupt number intnum. Unlike the _ int86 function, _ int86x accepts seg- 
ment-register values in segregs, enabling programs that use large-model data seg- 
ments or far pointers to specify which segment or pointer should be used during 
the system call. 


Before executing the specified interrupt, _ int86x copies the contents of inregs 
and segregs to the corresponding registers. Only the DS and ES register values in 
segregs are used. After the interrupt returns, the function copies the current regis- 
ter values to outregs, copies the current ES and DS values to segregs, and restores 
DS. It also copies the status of the system carry flag to the cflag field in outregs. 


The _ REGS and _SREGS types are defined in the include file DOS.H. 


Segment values for the segregs argument can be obtained by using either the 
_segread function or the _FP_SEG macro. 


Return Value The return value is the value in the AX register after the interrupt returns. If the 
cflag field in outregs is nonzero, an error has occurred; in such cases, the 
_ doserrno variable is also set to the corresponding error code. 


Compatibility Standards: None 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: None 


See Also _bdos, _FP_SEG, _ int86, _intdos, _ intdosx, _segread 


432 _ int86x 


Example /* INT86X.C: In this program, _int86x executes an INT 21H instruction 
* to invoke DOS system call 43H (change file attributes). The program 
* uses _int86x because the file, which is referenced with a far pointer, 
* may be in a segment other than the default data segment. Thus, the 
* program must explicitly set the DS register with the _SREGS structure. 
* / 


#tinclude <signal.h> 
fHinclude <dos.h> 
#Finclude <stdio.h> 
fHinclude <process.h> 


char __far *filename = " int86x.c"; 


void main( void ) 


{ 
union _REGS inregs, outregs; 
struct _SREGS segregs; 
int result; 
inregs.h.ah = Q@x43; /* DOS function to change attributes * / 
inregs.h.al = Q; /* Subfunction @ to get attributes) a / 
inregs.x.dx = _FP_OFF( filename ); /* DS:DX points to file name */ 
segregs.ds = _FP_SEG( filename ); 
result = _int86x( @x21, &inregs, &outregs, &Segregs ); 
if( outregs.x.cflag ) 
printf( "Can't get file attributes; error no. 4d\n", result); 
else 
printf( “Attribs = @x%.4x\n", outregs.x.cx ); 
} 


Output Attribs = 0x0020 


Description 


Remarks 


Return Value 


Compatibility 


See Also 
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_intdos 


Executes a DOS system call. 
#include <dos.h> 
int _intdos( union _REGS “*inregs, union _REGS “*outregs ); 


inregs Register values on call 


outregs Register values on return 


The _intdos function invokes the DOS system call specified by register values de- 
fined in inregs and returns the effect of the system call in outregs. The inregs and 
outregs arguments are unions of type _REGS. The _ REGS type is defined in the 
include file DOS.H. 


To invoke a system call, _intdos executes an INT 21H instruction. Before execut- 
ing the instruction, the function copies the contents of inregs to the corresponding 
registers. After the INT instruction returns, _intdos copies the current register 
values to outregs. It also copies the status of the system carry flag to the cflag field 
in outregs. A nonzero cflag field indicates the flag was set by the system call and 
also indicates an error condition. 


The _intdos function is used to invoke DOS system calls that take arguments for 
input or output in registers other than DX (DH/DL) and AL. The _intdos function 
is also used to invoke system calls that indicate errors by setting the carry flag. 
Under any other conditions, the _ bdos function can be used. 


Do not use the _intdos function to call interrupts that modify the DS register. 
Instead, use the _intdosx or _ int86x function. 


The _intdos function returns the value of the AX register after the system call is 
completed. If the cflag field in outregs is nonzero, an error has occurred and 
_doserrno is also set to the corresponding error code. 


Standards: None 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: None 


_bdos, _ intdosx 


434 _intdos 


Example /* INTDOS.C: This program uses _intdos to invoke DOS system call 2AH 
* (gets the current date). 
* / 


dFinclude <dos.h> 
dEinclude <stdio.h> 


void main( void ) 


{ 

union _REGS inregs, outregs; 

inregs.h.ah = Qx2a; /* DOS Get Date function: */ 

_intdos( &inregs, &outregs ); 

printf( "Date: %4d/%d/%Zd\n", outregs.h.dh, outregs.h.dl, outregs.x.cx ); 
} 


Output Date: 6/16/1999 
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_ intdosx 


Description Executes a DOS system call; accepts segment-register values. 
#include <dos.h> 


int _intdosx( union _REGS *inregs, union _REGS “outregs, 
struct _SREGS *segregs ); 


inregs Register values on call 
outregs Register values on return 
segregs Segment-register values on call 
Remarks The _intdosx function invokes the DOS system call specified by register values 


defined in inregs and returns the results of the system call in outregs. Unlike the 
_intdos function, _intdosx accepts segment-register values in segregs, enabling 
programs that use large-model data segments or far pointers to specify which seg- 
ment or pointer should be used during the system call. The REGS and _SREGS 
types are defined in the include file DOS.H. 


To invoke a system call, _intdosx executes an INT 21H instruction. Before ex- 
ecuting the instruction, the function copies the contents of inregs and segregs to 
the corresponding registers. Only the DS and ES register values in segregs are 
used. After the INT instruction returns, _intdosx copies the current register values 
to outregs and restores DS. It also copies the status of the system carry flag to the 
cflag field in outregs. A nonzero cflag field indicates the flag was set by the sys- 
tem call and also indicates an error condition. 


The _intdosx function is used to invoke DOS system calls that take an argument 
in the ES register or that take a DS register value different from the default data 
segment. 


Segment values for the segregs argument can be obtained by using either the 
_segread function or the _FP_SEG macro. 


Return Value The _intdosx function returns the value of the AX register after the system call is 
completed. If the cflag field in outregs is nonzero, an error has occurred; in such 
cases, _doserrno is also set to the corresponding error code. 
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Compatibility Standards: None 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: None 

See Also _bdos, _FP_SEG, _intdos, _ segread 


Example /* INTDOSX.C Sends a $-terminated string to the standard output device */ 


#tinclude <dos.h> 
d#Hinclude <stdio.h> 


char __far *buffer = "Dollar-sign terminated string\n\r\n\r$"; 


void main( void ) 


{ 
union _REGS inregs, outregs; 
struct _SREGS segregs; 
/* Print a $-terminated string on the screen using DOS function @x@9. */ 
inregs.h.ah = Qx9; 
inregs.x.dx = _FP_OFF( buffer ); 
segregs.ds = _FP_SEG( buffer ); 
_intdosx( &inregs, &outregs, &segregs ); 
} 


Output Dollar-sign terminated string 


Description 


Remarks 


is Functions 


is Functions 


Test characters for specified conditions. 
#include <ctype.h> 


int isalnum( int c ); 
int isalpha( int c ); 
int __ isascii( int c ); 
int iscntrl( int c ); 
int __iscsym( int c ); 
int __iscsymf( int c ); 
int isdigit( int c ); 

int isgraph( int c ); 
int islower( int c ); 
int isprint( int c ); 
int ispunct( int c ); 
int isspace( int c ); 
int isupper( int c ); 


int isxdigit( int c ); 


C Integer to be tested 


Each function in the is family tests a given integer value, returning a nonzero 
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value if the integer satisfies the test condition and 0 if it does not. The ASCII char- 


acter set is assumed. 
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Return Value 


Compatibility 


The is functions and their test conditions are listed below: 


Function Test Condition 

isalnum Alphanumeric (’A’—’Z’, ’a’—’z’, or ’0’—’9’) 
isalpha Letter ( A’—’Z’ or ’a’—’z’) 

__isascii ASCII character (0x00 — 0x7F) 

iscntrl Control character (0x00 — 0x1F or 0x7F) 
__iscsym Letter, underscore, or digit 

__iscsymf Letter or underscore 

isdigit Digit (0’-’9’) 

isgraph Printable character except space (’ ’) 

islower Lowercase letter ('a’—’z’) 

isprint Printable character (0x20 — 0x7E) 

ispunct Punctuation character 

isspace White-space character (0x09 — OxOD or 0x20) 
isupper Uppercase letter ( A’—’Z’) 

isxdigit Hexadecimal digit ( A’—’F’,’a’-’f’, or ’0’-’9’) 


The __isascii routine produces meaningful results for all integer values. However, 
the remaining routines produce a defined result only for integer values correspond- 
ing to the ASCII character set (that is, only where __isascii holds true) or for the 
non-ASCII value EOF (defined in STDIO.H). 


These routines are implemented both as functions and as macros. For details on 
choosing a function or a macro implementation, see “Choosing Between Functions 
and Macros” on page 9. 


These routines return a nonzero value if the integer satisfies the test condition and 
O if it does not. 


isalnum, isalpha, iscntrl, isdigit, peraph, islower, isprint, ispunct, isspace, 
isupper, isxdigit 


Standards: ANSI, UNIX 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 


See Also 


Example 


__isascil 

Standards: UNIX 

16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 


is Functions 
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Use __isascii for compatibility with ANSI naming conventions of non-ANSI func- 


tions. Use isascii and link with OLDNAMES.LIB for UNIX compatibility. 


__iscsym, __iscsymf 


Standards: 


16-Bit: 
32-Bit: 


None 


DOS, QWIN, WIN, WIN DLL 
DOS32X 


__toascii, tolower, toupper functions 


/* ISFAM.C: This program tests all characters between @x@ and Qx/F, 


* then displays each character with abbreviations for the character-type 


* codes that apply. 


* / 


#Hinclude <stdio.h> 
fHinclude <ctype.h> 


void main( void ) 


{ 


TInt. eh? 
for( ch = 0; ch <= @x/7F; cht+t ) 


{ 


printf ( 
printf ( 
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isprint( ch ) 
isalnum( ch ) 
isalpha( ch ) 


__isascii( ch ) 
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Output 


is Functions 
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Description 


Remarks 


Return Value 


_ isatty 4A1 
_ Isatty 
Checks for a character device. 
#include <io.h> Required only for function declarations 
int _isatty( int handle ); 


handle Handle referring to device to be tested 


The _isatty function determines whether handle is associated with a character 
device (a terminal, console, printer, or serial port). 


The _isatty function returns a nonzero value if the device is a character device. 
Otherwise, the return value is 0. 


Compatibility Standards: UNIX 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 


Example 


Output 


Use _isatty for compatibility with ANSI naming conventions of non-ANSI func- 
tions. Use isatty and link with OLDNAMES.LIB for UNIX compatibility. 


/* ISATTY.C: This program checks to see whether stdout has been 
* redirected to a file. 
* / 


d#Hinclude <stdio.h> 
d#Hinclude <io.h> 


void main( void ) 


{ 
if( _isatty( _fileno( stdout ) ) ) 
printf( “stdout has not been redirected to a file\n" ); 
else 
printf( “stdout has been redirected to a file\n"); 
j 


stdout has not been redirected to a file 
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Description 


Remarks 


Return Value 


_ttoa 


Converts an integer to a string. 
#include <stdlib.h> Required only for function declarations 


char *_itoa( int value, char “string, int radix ); 


value Number to be converted 
string String result 
radix Base of value 


The _itoa function converts the digits of the given value argument to a null- 
terminated character string and stores the result (up to 17 bytes) in string. The 
radix argument specifies the base of value; it must be in the range 2-36. If radix 
equals 10 and value is negative, the first character of the stored string is the minus 
sign (—). 


The _itoa function returns a pointer to string. There is no error return. 


Compatibility Standards: None 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 
See Also _Itoa, _ultoa 
Example /* ITOA.C: This program converts integers of various sizes to strings 


* in various radixes. 


* / 


#Hinclude <stdlib.h> 
d#Finclude <stdio.h> 


Output 


void main( void ) 


{ 


char buffer[20]; 


int 


; 


long | 
unsigned long ul = 123456/7890UL; 


= 3445; 
= -344115L; 


_itoa( i, buffer, 10 ); 

printf( "String of integer %d (radix 10): %s\n", i, buffer ); 
_itoa( i, buffer, 16 ); 

printf( "String of integer 4d (radix 16): Ox%s\n", 1, buffer ); 
_itoa( i, buffer, 2 ); 

printf( "String of integer %d (radix 2): %4s\n", i, buffer ); 


Itoa( 1, buffer, 16 ); 


_ itoa 


printf( "String of long int 4ld (radix 16): @x%s\n", 1, buffer ); 


_ultoa( ul, buffer, 16 ); 


printf( "String of unsigned long %lu (radix 16): @x%s\n", ul, buffer ); 


String 
String 
String 
String 
String 


of 
of 
OT 
of 
of 


integer 3445 (radix 10): 3445 

integer 3445 (radix 16): Q@xd75 

integer 3445 (radix 2): 110101110101 

long int -344115 (radix 16): Oxfffabfcd 
unsigned long 1234567890 (radix 16): 0x49960@2d2 
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444 —_kbhit 


Description 


Remarks 


Return Value 


Compatibility 


_kbhit 


Checks the console for keyboard input. 
#include <conio.h> Required only for function declarations 


int _kbhit( void ); 


The _ kbhit function checks the console for a recent keystroke. If the function re- 
turns a nonzero value, a keystroke is waiting in the buffer. The program can then 
call _getch or _ getche to get the keystroke. 


The _ kbhit function returns a nonzero value if a key has been pressed. Otherwise, 
it returns 0. 


Standards: None 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 


Example /* KBHIT.C: This program loops until the user presses a key. 
* If _kbhit returns nonzero, a keystroke is waiting in the buffer. 
* The program can call _getch or _getche to get the keystroke. 


* / 


d#Hinclude <conio.h> 
dEinclude <stdio.h> 


void main( void ) 


{ 
/* Display message until key is pressed. */ 
while( !_kbhit() ) 
JCOUrsSe Hit Mell & je 
/* Use _getch to throw key away. */ 
printf( "\nkKey struck was ‘%c'\n", _getch() ); 
_getch(); 
} 
Output Hit me!! Hit me!! Hit me!! Hit me!! Hit me!! Hit me!! Hit me!! 


Key struck was ‘k’' 
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labs 


Description Calculates the absolute value of a long integer. 
#include <stdlib.h> Required only for function declarations 
#include <math.h> 
long labs( long 7 ); 
n Long-integer value 
Remarks The labs function produces the absolute value of its long-integer argument n. 
Return Value The labs function returns the absolute value of its argument. There is no error 
return. 
Compatibility Standards: ANSI 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 
See Also abs, _ cabs, fabs 


Example /* ABS.C: This program computes and displays the absolute values of 
* several numbers. 
* / 


deinclude <stdio.h> 
dAinclude <math.h> 
dAinclude <stdlib.h> 
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void main( void ) 

{ 
int 1X “A Ty 
long 1x = -41567L, ly; 
double dx = -3.141593, dy; 


iy = abs( ix ); 
printf( "The absolute value of 4d is %d\n", ix, iy); 


ly = labs( 1x ); 
printf( "The absolute value of 4Ild is &4ld\n", 1x, ly); 


dy = fabs( dx ); 
printf( "The absolute value of 4“f is %f\n", dx, dy ); 


Output The absolute value of -4 is 4 
The absolute value of -41567 is 41567 
The absolute value of -3.141593 is 3.141593 


Description 


Remarks 


Return Value 


Compatibility 


See Also 


Idexp, _Idexpl AAT 


Idexp, _ Idexpl 


Compute a real number from the mantissa and exponent. 
#include <math.h> 


double Idexp( double x, int exp ); 


long double _ Idexpl( long double x, int exp ); 


x Floating-point value 


exp Integer exponent 


The Idexp and _Idexpl functions calculate the value of x * 2°”. 


The Idexp and _Idexpl functions return x * 2°?. If an overflow results, the 
functions return + HUGE_ VAL (depending on the sign of x) and set errno to 
ERANGE. 


The _Idexpl function uses the 80-bit, 10-byte coprocessor form of arguments and 
return values. See the reference page on the long double functions for more details 
on this data type. | 


Idexp 

Standards: ANSI, UNIX 

16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 

_Idexpl 

Standards: None 

16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: None 


frexp, modf 
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Example /* LDEXP.C */ 
dEinclude <math.h> 
d#Einclude <stdio.h> 


void main( void ) 

{ 
double x = 4.0, y; 
int p = 3; 


y = Idexp( x, p ); 
printf( "%2.1f times two to the power of 4d is %42.1f\n", x, p, y ); 


Output 4.@ times two to the power of 3 is 32.0 


Description 


Remarks 


Return Value 


Compatibility 


See Also 
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ldiv 
Computes the quotient and remainder of a long integer. 
#include <stdlib.h> 


Idiv_t Idiv ( long int numer, long int denom ); 


numer Numerator 


denom Denominator 


The Idiv function divides numer by denom, computing the quotient and the re- 
mainder. The sign of the quotient is the same as that of the mathematical quotient. 
Its absolute value is the largest integer that is less than the absolute value of the 
mathematical quotient. If the denominator is 0, the program will terminate with an 
error message. 


The Idiv function is similar to the div function, with the difference being that the 
arguments and the members of the returned structure are all of type long int. 


The Idiv_t structure, defined in STDLIB.H, contains the following elements: 


Element Description 
long int quot Quotient 
long int rem Remainder 


The Idiv function returns a structure of type Idiv_t, comprising both the quotient 
and the remainder. 


Standards: ANSI 


16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 
div 
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Example 


Output 


Idiv 


/* LDIV.C: This program takes two long integers as command-line 
* arguments and displays the results of the integer division. 
* / 


d#Hinclude <stdlib.h> 
#Hinclude <math.h> 
d#Ainclude <stdio.h> 


void main( void ) 

{ 
long x = 5149627, y = 234879; 
Ildiv_t div_result; 


div_result = ldiv( x, y ); 

printf( "For %ld / 41d, the quotient is ", x, y ); 

printf( "%ld, and the remainder is %1d\n", 
div_result.quot, div_result.rem ); 


For 5149627 / 234879, the quotient is 21, and the remainder is 217168 


Description 


Remarks 


Return Value 
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_Ifind 
Performs a linear search for the specified key. 
#include <search.h> Required only for function declarations 


void *_lfind( const void *key, const void *base, unsigned int *num, 
unsigned int width, int (__.cdecl *compare )( const void *elem/, 
const void *elem2 ) ); 


key Object to search for 

base Pointer to base of search data 

num Number of array elements 

width Width of array elements 

compare( ) Pointer to comparison routine 

elem] Pointer to the key for the search 

elem2 Pointer to the array element to be compared with 
the key 


The _lfind function performs a linear search for the value key in an array of num 
elements; each element is width bytes in size. (Unlike bsearch, _ Ifind does not 
require the array to be sorted.) The base argument is a pointer to the base of the 
array to be searched. 


The compare argument is a pointer to a user-supplied routine that compares two 
array elements and then returns a value specifying their relationship. The _Ifind 
function calls the compare routine one or more times during the search, passing 
pointers to two array elements on each call. This routine must compare the ele- 
ments, then return one of the following values: 


Value Meaning 
Nonzero Elements are different 
0 Elements are identical 


If the key is found, _Ifind returns a pointer to the element of the array at base that 
matches key. If the key is not found, _ Ifind returns NULL. 
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_ find 


Compatibility — Standards: UNIX 


See Also 


Example 


Output 


16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 


Use _Ifind for compatibility with ANSI naming conventions of non-ANSI func- 
tions. Use Ifind and link with OLDNAMES.LIB for UNIX compatibility. 


bsearch, _ Ilsearch, qsort 


/* LFIND.C: This program uses _lfind to search for the word "hello" 
* jn the command-line arguments. 
* / 


d#Hinclude <search.h> 
#tinclude <string.h> 
d#Hinclude <stdio.h> 


int compare( void *argl, void *arg2 ); 


void main( int argc, char **argv ) 
{ 

char **result; 

char *key = "hello"; 


result = (char **)_ lfind( &key, argv, 
&argc, sizeof( char * ), compare ); 
if( result ) 
printf( "%s found\n", *result ); 
else 
printf( "hello not found!\n" ); 
} 


int compare(void *argl, void *arg2 ) 
{ 
return( _stricmp ( * ( char** ) argl, * ( char** ) arg2 ); 


} 


[C:\LIBREF] _1lfind What if I said Hello world 
Hello found 


_lineto Functions 453 


_lineto Functions 


Description Draw lines to specified points. 
#include <graph.h> 


short __far _lineto( short x, short y ); 


short __far _lineto_w( double wx, double wy ); 


x,y End point 
wx, Wy End point 
Remarks The functions in the _lineto family draw a line from the current graphics position 


up to and including the destination point. The destination point for the _lineto 
function is given by the view-coordinate point (x, y). The destination point for the 
_lineto_w function is given by the window-coordinate point (wx, wy). 


The line is drawn using the current color, logical write mode, and line style. If no 
error occurs, _ lineto sets the current graphics position to the view-coordinate 
point (x, y); _lineto_w sets the current position to the window-coordinate point 
(wx, wy). 


If you use _floodfill to fill in a closed figure drawn with _lineto calls, the figure 
must be drawn with a solid line-style pattern. 


Return Value The _lineto and _lineto_w routines return a nonzero value if anything is drawn; 
otherwise, they return 0. 


Compatibility Standards: None 
16-Bit: DOS 
32-Bit: None 


See Also _getcurrentposition functions, _moveto functions, _setlinestyle 
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Example /* MOVETO.C: This program draws line segments of different colors. */ 


#Finclude <graph.h> 
dHinclude <stdlib.h>. 
#Hinclude <conio.h> 


void main( void ) 

{ 
short x, y, Xinc, yinc, color = 1; 
struct _videoconfig v; 


/* Find a valid graphics mode. */ 

if( !_setvideomode( _MAXCOLORMODE ) ) 
exit( 1 ); 

_getvideoconfig( &v ); 

xinc = v.numxpixels / 5@; 

yinc = v.numypixels / 5; 


for( x = @, y = v.numypixels - 1; x < v.numxpixels; X += xinc, y -= yinc ) 

{ / 
-gsetcolor® colort 4% 16.9; 
_moveto( x, @ ); 
_lineto( @, y ); 

} 

_getch(); 


_setvideomode( _DEFAULTMODE ); 
exit( @ ); 


Description 


Remarks 


localeconv 


localeconv 455 


Gets detailed information on locale settings. 


#include <locale.h> 


struct Iconv *localeconv( void ); 


The localeconv function gets detailed information on the locale-specific settings 
for numeric formatting of the program’s current locale. This information is stored 


in a structure of type Iconv. 


The Iconv structure, defined in LOCALE.H, contains the following members: 


Member 


char *decimal_ point 
char *thousands_ sep 


char *grouping 
char *int_curr_symbol 


char *currency_ symbol 
char *mon_decimal_ point 
char *mon_thousands_ sep 


char *mon_ grouping 
char *positive_sign 


char *“negative_sign 
char int_frac_digits 


char frac_ digits 


Description 


Decimal-point character for nonmonetary quantities. 


Character used to separate groups of digits to the left 
of the decimal point for nonmonetary quantities. 


Size of each group of digits in nonmonetary quantities. 


International currency symbol for the current locale. 
The first three characters specify the alphabetic 
international currency symbol as defined in the /SO 
4217 Codes for the Representation of Currency and 
Funds standard. The fourth character (immediately 
preceding the null character) is used to separate the 
international currency symbol from the monetary 
quantity. 

Local currency symbol for the current locale. 
Decimal-point character for monetary quantities. 


Separator for groups of digits to the left of the decimal 
place in monetary quantities. 


Size of each group of digits in monetary quantities. 


String denoting sign for nonnegative monetary 
quantities. 


String denoting sign for negative monetary quantities. 


Number of digits to the right of the decimal point in 
internationally formatted monetary quantities. 
Number of digits to the right of the decimal point in 
formatted monetary quantities. 
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Member Description 


char p_cs_ precedes Set to 1 if the currency symbol precedes the value for 
a nonnegative formatted monetary quantity. Set to 0 if 
the symbol follows the value. 


char p_sep_ by_space Set to 1 if the currency symbol is separated by a space 
from the value for a nonnegative formatted monetary 
quantity. Set to O if there is no space separation. 

char n_cs_ precedes Set to 1 if the currency symbol precedes the value for 
a negative formatted monetary quantity. Set to 0 if the 
symbol succeeds the value. 

char n_sep_by_space Set to 1 if the currency symbol is separated by a space 
from the value for a negative formatted monetary 
quantity. Set to O if there is no space separation. 

char p_sign_posn Position of positive sign in nonnegative formatted 
monetary quantities. 

char n_sign_posn Position of positive sign in negative formatted 
monetary quantities. 


The char * members of the struct are pointers to strings. Any of these (other than 
char *decimal_ point) that equals "" is either of zero length or is not supported in 
the current locale. The char members of the struct are nonnegative numbers. Any 
of these that equals CHAR_ MAX is not supported in the current locale. 


The elements of grouping and mon_ grouping are interpreted according to the 


following rules: 

Value Interpretation 

CHAR_ MAX No further grouping is to be performed. 

0 The previous element is to be repeatedly used for the remainder 
of the digits. | 

n The integer value n is the number of digits that make up the 


current group. The next element is examined to determine the 
size of the next group of digits before the current group. 


The values for p_sign_posn and n_sign_posn are interpreted according to the 


following rules: 

Value Interpretation 

0 Parentheses surround the quantity and currency symbol 
1 Sign string precedes the quantity and currency symbol 
2 Sign string follows the quantity and currency symbol 

3 Sign string immediately precedes the currency symbol 
4 Sign string immediately follows the currency symbol 


Return Value 


Compatibility 


See Also 
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The localeconvy function returns a pointer to a filled in object of type struct Iconv. 
The values contained in the object can be overwritten by susequent calls to 
localeconvy and do not directly modify the object. Calls to the setlocale function 
with category values of LC_ALL, LC_MONETARY, or LC_NUMERIC 

will overwrite the contents of the structure. 


Standards: ANSI 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 


setlocale, strcoll, strftime, strxfrm 
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Description 


Remarks 


localtime 


Converts a time value and corrects for the local time zone. 
#include <time.h> 
struct tm *localtime( const time_t *timer ); 


timer Pointer to stored time 


The localtime function converts a time stored as a time_t value and stores the re- 
sult in a structure of type tm. The long value timer represents the seconds elapsed 
since midnight (00:00:00), December 31, 1899, Universal Coordinated Time. This 
value is usually obtained from the time function. 


The fields of the structure type tm store the following values: 


Element Value Stored 

int tm_sec Seconds 

int tm_min Minutes 

int tm_hour Hours (0 —24) 

int tm_mday Day of month (1-31) 

int tm_mon Month (0-11; January = 0) 

int tm_year Year (current year minus 1900) 

int tm_wday Day of week (0—6; Sunday = 0) 

int tm_yday Day of year (0-365; January 1 = 0) 

int tm_isdst Nonzero if daylight saving time is in effect, otherwise 0 


Note that the gmtime, mktime, and localtime functions use a single statically allo- 
cated tm structure for the conversion. Each call to one of these routines destroys 
the result of the previous call. 


The localtime function makes corrections for the local time zone if the user first 
sets the environment variable TZ. When TZ is set, three other environment varia- 
bles (_ timezone, _ daylight, and _tzname) are automatically set as well. See 
_tzset for a description of these variables. 


The TZ variable is not part of the ANSI standard definition of localtime but is a 
Microsoft extension. 
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Return Value The localtime function returns a pointer to the structure result. If the value in 
timer represents a date before midnight, December 31, 1899, the function returns 
NULL. 

Compatibility Standards: ANSI, UNIX 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 

See Also asctime, ctime, _ ftime, gmtime, time, _ tzset 


Example /* LOCALTIM.C: This program uses time to get the current time and 

then uses localtime to convert this time to a structure representing 
the local time. The program converts the result from a 24-hour clock 
* to a 12-hour clock and determines the proper extension (AM or PM). 

* / 


* 


4#FAinclude <stdio.h> 
dFinclude <string.h> 
d4Finclude <time.h> 


void main( void ) 


{ 
struct tm *newtime; 
char am_pm[] = "AM"; 
time_t long _time; 
time( &long_time ); /* Get time as long integer. */ 
newtime = localtime( &long_time ); /* Convert to local time. */ 
if( newtime->tm_hour < 12 ) /* Set up extension. */ 
strcpy( am_pm, "AM" ); 
if( newtime->tm_hour > 12 ) /* Convert from 24-hour */ 
newtime->tm_hour -=12; /* to 12-hour clock. = */ 
printf( "%.19s %s\n", asctime( newtime ), am_pm ); 
} 


Output Fri Jun 16 06:27:02 AM 
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_ locking 
Description Locks or unlocks bytes of a file. 


#include <sys\locking.h> 


#include <io.h> Required only for function declarations 


int _locking( int handle, int mode, long nbytes ); 


handle File handle 
mode File-locking mode 
nbytes Number of bytes to lock 
Remarks The _locking function locks or unlocks nbytes bytes of the file specified by 


handle. Locking bytes in a file prevents access to those bytes by other processes. 
All locking or unlocking begins at the current position of the file pointer and 
proceeds for the next nbytes bytes. It 1s possible to lock bytes past the end of the 
file. 


The mode argument specifies the locking action to be performed. It must be one of 
the following manifest constants: 


Constant Action 


_LK_LOCK Locks the specified bytes. If the bytes cannot be locked, 
immediately tries again after 1 second. If, after 10 attempts, the 
bytes cannot be locked, returns an error. 


_LK_NBLCK Locks the specified bytes. If bytes cannot be locked, returns an 
error. 

_LK_NBRLCK Same as _LK_NBLCK. 

_LK_RLCK Same as _LK_LOCK. 

_LK_UNLCK Unlocks the specified bytes. (The bytes must have been 


previously locked.) 


More than one region of a file can be locked, but no overlapping regions are 
allowed. 


When a region of a file is being unlocked, it must correspond to a region that was 
previously locked. The _ locking function does not merge adjacent regions; if two 
locked regions are adjacent, each region must be unlocked separately. 


Return Value 


_ locking 461 


Regions should be locked only briefly and should be unlocked before closing a file 
or exiting the program. 


The _ locking function should be used only with DOS versions 3.0 and later; it has 
no effect under earlier versions of DOS. Also, file sharing must be loaded to use 
the _locking function. Note that with DOS versions 3.0 and 3.1, the files locked 
by parent processes may become unlocked when child processes exit. 


The _ locking function returns 0 if successful. A return value of —1 indicates 
failure, and errno is set to one of the following values: 


Value Meaning 
EACCES Locking violation (file already locked or unlocked). 
EBADF Invalid file handle. 
EDEADLOCK Locking violation. This is returned when the _LK_LOCK or 
_LK_RLCK flag is specified and the file cannot be locked after 
10 attempts. 
EINVAL An invalid argument was given to the function. 
Compatibility Standards: UNIX 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 
Use _locking for compatibility with ANSI naming conventions of non-ANSI func- 
tions. Use locking and link with OLDNAMES.LIB for UNIX compatibility. 
See Also _creat, _ open 
Example /* LOCKING.C: This program opens a file with sharing. It locks some 


* bytes 
* works 
ge z 
se = 


* / 


#tinclude 
#Finclude 
#tinclude 
#tinclude 
#Hinclude 
d#tinclude 
#include 
#include 


before reading them, then unlocks them. Note that the program 
correctly only if the following conditions are met: 

The file exists 

The program is run with DOS version 3.@ or later 

with file sharing installed (SHARE.COM or SHARE.EXE), or 

if a Microsoft Networks compatible network is running 


<io.h> 
<sys\types.h> 
<sys\stat.h> 
<sys\locking.h> 
<share.h> 
<fentl.h> 
<stdio.h> 
<stdlib.h> 
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Output 


_ locking 


void main( void ) 


{ 


int fh, numread; 
long pos, result; 
char bufferl4@]; 


/* Quit if can't open file or DOS version doesn't support sharing. */ 
fh = _sopen( "locking.c", _O_RDWR, _SH_DENYNO, _S_IREAD | _S_IWRITE ); 
if( (fh == -1) || (_osmajor < 3) ) 

exit( 1 ); 


/* Lock some bytes and read them. Then unlock. */ 
if( _locking( fh, LK_NBLCK, 30L ) != -1 ) 
‘ 
printf( "No one can change these bytes while I'm reading them\n" ); 
numread = _read( fh, buffer, 30 ); 
printf( "%d bytes read: %.30s\n", numread, buffer ); 
_locking( fh, LK_UNLCK, 30L ); 
printf( "Now I'm done. Do what you will with them\n" ); 
i 
else 
perror( "Locking failed\n" ); 


_close( fh ); 


No one can change these bytes while I'm reading them 
3@ bytes read: /* LOCKING.C: This program open 
Now I'm done. Do what you will with them 


Description 


Remarks 


Return Value 


Compatibility 
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log Functions 


Calculate logarithms. 
#include <math.h> 


double log( double x ); 

double log10( double x ); 

long double _logl( long double x ); 
long double _log101( long double x ); 


x Value whose logarithm is to be found 


The log and log10 functions calculate the natural logarithm and the base-10 loga- 
rithm, respectively, of x. The _logl and _log101 functions are the 80-bit counter- 
parts and use the 80-bit, 10-byte coprocessor form of arguments and return values. 
See the reference page on the long double functions for more details on this data 


type. 


The log functions return the logarithm of the argument x. If x is negative, the func- 
tions print a_ DOMAIN error message to stderr, return the value -HUGE_ VAL, 
and set errno to EDOM. If x is 0, the functions print a__SING error message to 
stderr, return the value -HUGE_ VAL, and set errno to ERANGE. 


Error handling can be modified by using the _ matherr or _ matherrl routine. 


log, log10 
Standards: ANSI, UNIX 
16-Bit: DOS, QWIN, WIN, WIN DLL 


32-Bit: DOS32X 
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_logl, _log101 
Standards: None 


16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: None 
See Also exp, _matherr, pow functions 


Example /* LOG.C: This program uses log and 10g1@ to calculate the natural 
* logarithm and the base-1@ logarithm of 9,000. 
* / 


dEinclude <math.h> 
d4tinclude <stdio.h> 


void main( void ) 


{ 
double x = 9000.0; 
double y; 
y = log( x ): 


printf( "log( %.2f ) = “f\n", x, y );3 
y = 1logl1@( x ); 
printf( "logl@( %.2f ) 


i WM 4° hay Oe 


} 
Output log( 9000.00 ) = 9.104980 
logl@( 9000.00 ) = 3.954243 
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long double Functions 


The 8087 family of numeric coprocessor chips supports the 80-bit precision float- 
ing-point data type. Beginning with Microsoft C version 6.0, the long double func- 
tions, whose names end with I, map the C long double type into this 80-bit, 
10-byte form. Unlike the regular floating-point functions (such as acos), which re- 
turn values of type double, these long double functions (such as _ acosl) return 
values of type long double. The long double functions also return their values on 
the coprocessor stack for all calling conventions. 


The long double type is also supported by the addition of the “L” prefix for a 
floating-point format specification in the printf and scanf family of functions. 


The long double versions are described on the reference pages for their regular 
counterparts. These are the regular run-time math functions with corresponding 
long double equivalents: 


Function Long Double Form Function Long Double Form 
acos _acosl frexp _frexpl 
asin _asinl _hypot _hypotl 
atan _atanl Idexp _idexpl 
atan2 _atan2!1 log _logl 

atof _atold log10 _log101 
_cabs _cabsl _matherr _matherrl 
ceil _ceill modf _modfl 
cos _cosl pow _powl 
cosh _coshl sin _ sini 

exp _expl sinh _sinhl 
fabs _fabsl sqrt _sqrtl 
floor _ floor! tan _tanl 


fmod _fmodl tanh _tanhl 
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Description 


Remarks 


longjmp 


Restores stack environment and execution locale. 
#include <setjmp.h> 
void longjmp( jmp_ buf env, int value ); 


env Variable in which environment is stored 


value Value to be returned to setjmp call 


The longjmp function restores a stack environment and execution locale pre- 
viously saved in env by setjmp. The setjmp and longjmp functions provide a way 
to execute a nonlocal goto; they are typically used to pass execution control to 
error handling or recovery code in a previously called routine without using the 
normal call and return conventions. 


A call to setjmp causes the current stack environment to be saved in env. A sub- 
sequent call to longjmp restores the saved environment and returns control to the 
point immediately following the corresponding setjmp call. Execution resumes as 
if value had just been returned by the setjmp call. The values of all variables (ex- 
cept register variables) that are accessible to the routine receiving control contain 
the values they had when longjmp was called. The values of register variables are 
unpredictable. 


The longjmp function must be called before the function that called setjmp re- 
turns. If longjmp is called after the function calling setjmp returns, unpredictable 
program behavior results. 


The value returned by setjmp must be nonzero. If value is passed as 0, the value 1 
is substituted in the actual return. 


Observe the following four restrictions when using longjmp: 


= Do not assume that the values of the register variables will remain the same. 
The values of register variables in the routine calling setjmp may not be re- 
stored to the proper values after longjmp is executed. Do not use longjmp with 
the global register allocation (/Oe) option to the CL driver. 


= Do not use longjmp to transfer control from within one overlay to within 
another. The overlay manager keeps the overlay in memory after a call to 
longjmp. | 


Return Value 


Compatibility 


See Also 


Example 
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= Do not use longjmp to transfer control out of an interrupt-handling routine un- 
less the interrupt is caused by a floating-point exception. In this case, a program 
may return from an interrupt handler via longjmp if it first reinitializes the 
floating-point math package by calling _ fpreset. 


=" Do not use longjmp or setjmp from a C++ program. 
None. 


Standards: ANSI, UNIX 


16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 
setjmp 


See the example for _fpreset. 
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_trotl, _lrotr 


Description Rotate bits to the left (_ lrotl) or right (_Irotr). 


#include <stdlib.h> 


unsigned long _ Irotl( unsigned long value, int shift ); 


unsigned long _ lrotr( unsigned long value, int shift ); 


value Value to be rotated 
shift Number of bits to shift 
Remarks The _Irotl and _lrotr functions rotate value by shift bits. The _lrotl function 


rotates the value left. The _lrotr function rotates the value right. Both functions 
“wrap” bits rotated off one end of value to the other end. 


Return Value Both functions return the rotated value. There is no error return. 
Compatibility Standards: None 

16-Bit: DOS, QWIN, WIN, WIN DLL 

32-Bit: DOS32X 
See Also _rotl, _rotr 


Example /* LROT.C */ 
dEinclude <stdlib.h> 
dEinclude <stdio.h> 


void main( void ) 


{ 
unsigned long val = @x@fac35/91; 
printf( "Q@x%8.81x rotated left eight times is @x%8.81x\n", 
val, _lrotl( val, 8 ) ); 
printf( "@x%8.81x rotated right four times is @x%8.81x\n", 
val, _lrotr( val, 4 ) ); 
7 
Output xfac35791 rotated left eight times is @xc3579lfa 


@xfac35791 rotated right four times is @xlfac35/79 


Description 


Remarks 


Return Value 
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_ lsearch 


Performs a linear search for a value; adds to end of list if not found. 
#include <search.h> Required only for function declarations 


void *_lsearch( const void *key, const void *base, unsigned int *num, 
unsigned int width, int (__cdecl *compare )( const void *elem1/, 
const void “elem2 ) ); 


key Object to search for 

base Pointer to base of search data 

num Number of elements 

width Width of elements 

compare Pointer to comparison routine 

elem! Pointer to the key for the search 

elem2 Pointer to the array element to be compared with 
the key 


The _Isearch function performs a linear search for the value key 1n an array of 
num elements, each of width bytes in size. (Unlike bsearch, _ lsearch does not re- 
quire the array to be sorted.) The base argument is a pointer to the base of the 
array to be searched. 


If key is not found, _ Isearch adds it to the end of the array. 


The compare argument is a pointer to a user-supplied routine that compares two 
array elements and returns a value specifying their relationship. The _lsearch 
function calls the compare routine one or more times during the search, passing 
pointers to two array elements on each call. This routine must compare the ele- 
ments, then return one of the following values: 


Value Meaning 
Nonzero Elements are different 
0 | Elements are identical 


If the key is found, _Isearch returns a pointer to the element of the array at base 
that matches key. If the key is not found, _ Isearch returns a pointer to the newly 
added item at the end of the array. 
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Compatibility Standards: UNIX 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 


Use _Isearch for compatibility with ANSI naming conventions of non-ANSI func- 
tions. Use Isearch and link with OLDNAMES.LIB for UNIX compatibility. 


See Also bsearch, _ lfind 


Example See the example for _ find. 


Description 


Remarks 


Return Value 
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_lseek 
Moves a file pointer to the specified location. 


#include <io.h> Required only for function declarations 


#include <stdio.h> 


long _lseek( int handle, long offset, int origin ); 


handle Handle referring to open file 
offset Number of bytes from origin 
origin Initial position 


The _Iseek function moves the file pointer associated with handle to a new loca- 
tion that is offset bytes from origin. The next operation on the file occurs at the 
new location. The origin argument must be one of the following constants, which 
are defined in STDIO.H: 


Origin Definition 

SEEK_SET Beginning of file 
SEEK_CUR Current position of file pointer 
SEEK_END End of file 


The _Iseek function can be used to reposition the pointer anywhere in a file. The 
pointer can also be positioned beyond the end of the file. However, an attempt to 
position the pointer before the beginning of the file causes an error. 


The _Iseek function returns the offset, in bytes, of the new position from the begin- 
ning of the file. The function returns —1L to indicate an error and sets errno to one 
of the following values: 


Value Meaning 
EBADF Invalid file handle 
EINVAL Invalid value for origin, or position specified by offset is before 


the beginning of the file 


On devices incapable of seeking (such as terminals and printers), the return value 
is undefined. 
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Compatibility Standards: UNIX 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 


Use _Iseek for compatibility with ANSI naming conventions of non-ANSI func- 
tions. Use Iseek and link with OLDNAMES.LIB for UNIX compatibility. 


See Also fseek, _ tell 


Example /* LSEEK.C: This program first opens a file named LSEEK.C. 
* It then uses _lseek to find the beginning of the file, 
* to find the current position in the file, and to find 
* the end of the file. 
* / 


#Hinclude <io.h> 

#Hinclude <fcntl.h> 
#Hinclude <stdlib.h> 
4#Hinclude <stdio.h> 


void main( void ) 

{ 
int fh; 
long pos; /* Position of file pointer */ 
char buffer[1@]; 


fh = _open( "Iseek.c", _O_RDONLY ); 


/* Seek the beginning of the file: */ 
pos = _lseek( fh, @L, SEEK_SET ); 
if(@ pos ==. -1L. ) 
perror( "_lseek to beginning failed” ); 
else 
printf( "Position for beginning of file seek = %ld\n", pos ); 


/* Move file pointer a little */ 
_read( fh, buffer, 10 ); 


/* Find current position: */ 
pos = _lseek( fh, @L, SEEK_CUR ); 
if( pos == -1L ) 
perror( "_lseek to current position failed” ); 
else 
printf( "Position for current position seek = 4]ld\n", pos ); 


Output 


_ lseek 


/* Set the end of the file: */ 
pos = _lseek( fh, @L, SEEK_END ); 
if( pos == -1L ) 
perror( "_lseek to end failed" ); 
else 
printf( "Position for end of file seek = %ld\n", pos ); 


_close( fh ); 


Position for beginning of file seek = Q 
Position for current position seek = 10 
Position for end of file seek = 1183 
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474 _ toa 


Description 


Remarks 


Return Value 


_ toa 


Converts a long integer to a string. 
#include <stdlib.h> Required only for function declarations 


char *_Itoa( long value, char *string, int radix ); 


value Number to be converted 
string String result 
radix Base of value 


The _ltoa function converts the digits of value to a null-terminated character 
string and stores the result (up to 33 bytes) in string. The radix argument specifies 
the base of value, which must be in the range 2—36. If radix equals 10 and value is 
negative, the first character of the stored string is the minus sign (—). 


The _ltoa function returns a pointer to string. There is no error return. 


Compatibility Standards: None 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 
See Also _itoa, _ultoa 
Example /* ITOA.C: This program converts integers of various sizes to strings 


* in various radixes. 


* / 


dHinclude <stdlib.h> 
dinclude <stdio.h> 


Output 


void main( void ) 


{ 


char buffer[2Q]; 


int 


j 


long | 
unsigned long ul = 1234567890UL; 


= 3445; 
= -344115L; 


_itoa( i, buffer, 1@ ); 


printf( "String of integer 4d (radix 10): 4s\n", i, buffer ); 


_itoa( i, buffer, 16 ); 
printf( "String of integer 4d (radix 16): Ox%s\n", 1, buffer ); 
_itoa( i, buffer, 2 ); 


printf( "String of integer 4d (radix 2): %4s\n", i, buffer ); 


_Itoa( 1, buffer, 16 ); 
printf( "String of long int 4Ild (radix 16): @x%s\n", 1, buffer ); 


_ultoa( ul, buffer, 16 ); 


printf( "String of unsigned long 4lu (radix 16): @x%s\n", ul, buffer ); 


String 
String 
String 
String 
String 


of 
of 
of 
of 
of 


integer 3445 (radix 10): 3445 

integer 3445 (radix 16): @xd75 

integer 3445 (radix 2): 110101110101 

long int -344115 (radix 16): Oxfffabfcd 
unsigned long 1234567890 (radix 16): 0x49960@2d2 


_Itoa 
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476 _makepath 


Description 


Remarks 


_makepath 


Creates a path name from components. 
#include <stdlib.h> 


void _makepath( char *path, char *drive, char “dir, char *fname, char *ext ); 


path Full path-name buffer 
drive Drive letter 

dir Directory path 

fname Filename 

ext File extension 


The _makepath routine creates a single path name, composed of a drive letter, 
directory path, filename, and filename extension. The path argument should point 
to an empty buffer large enough to hold the complete path name. The constant 
_MAX_ PATH, defined in STDLIB.H, specifies the maximum size path that the 
_makepath function can handle. The other arguments point to buffers containing 
the path-name elements: 


Buffer Description 


drive The drive argument contains a letter (A, B, etc.) corresponding to the 
desired drive and an optional trailing colon. The _makepath routine 
will insert the colon automatically in the composite path name if it is 
missing. If drive is a null character or an empty string, no drive letter 
and colon will appear in the composite path string. 


dir The dir argument contains the path of directories, not including the 
drive designator or the actual filename. The trailing slash is optional, 
and either forward slashes ( \) or backslashes (\ ) or both may be 
used in a single dir argument. If a trailing slash (/ or \ ) is not 
specified, it will be inserted automatically. If dir is a null character or 
an empty string, no slash is inserted in the composite path string. 


jJname The fname argument contains the base filename without any 
extensions. If fname is NULL or points to an empty string, no 
filename is inserted in the composite path string. 
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Buffer Description 


ext The ext argument contains the actual filename extension, with or 
without a leading period (.). The _makepath routine will insert the 
period automatically if it does not appear in ext. If ext is a null 
character or an empty string, no period is inserted in the composite 
path string. 


There are no size limits on any of the above four fields. However, the composite 
path must be no larger than the MAX_ PATH constant. The MAX_ PATH 
limit permits a path name much larger than current operating-system versions will 


handle. 

Return Value None. 

Compatibility Standards: None 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 

See Also _fullpath, _splitpath 


Example /* MAKEPATH.C */ 
#Finclude <stdlib.h> 
#Hinclude <stdio.h> 


void main( void ) 
{ 
char path_buffer[L_MAX_ PATH]; 
char drive[_MAX_DRIVE]; 
char dirL_MAX_DIR]; 
char fname[l_MAX_ FNAME]; 
char extl_MAX_EXT]; 


_makepath( path_buffer, "c", "\\c6@\\clibref\\", "makepath", "c" ); 
printf( "Path created with _makepath: %s\n\n", path_buffer ); 
_splitpath( path_buffer, drive, dir, fname, ext ); 

printf( "Path extracted with _splitpath:\n" ); 

printf( " Drive: %s\n", drive ); 

printf( " Dir: %4s\n", dir ); 

printf( " Filename: %s\n", fname ); 

printf( " Ext: %s\n", ext ); 
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Output Path created with _makepath: c:\c6@\clibref\makepath.c 


Path extracted with _splitpath: 
Drive: Cc: 
Dir: \c6@\clibref\ 
Filename: makepath 
ECS | ot 


Description 


Remarks 


malloc Functions 


malloc Functions 


Allocate memory blocks. 


#include <stdlib.h> For ANSI compatibility (malloc only) 


#include <malloc.h> Required only for function declarations 


void *malloc( size_t size ); 
void __ based(void) *_ bmalloc( __ segment seg, size_t size ); 
void __ far *_fmalloc( size_t size ); 


void __ near *_nmalloc( size_t size ); 


size Bytes to allocate 


seg Based heap segment selector 
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Functions in the malloc family allocate a memory block of at least size bytes. The 


block may be larger than size bytes because of space required for alignment and 
maintenance information. If size is 0, each of these functions allocates a zero- 


length item in the heap and returns a valid pointer to that item. 


The storage space pointed to by the return value is guaranteed to be suitably 


aligned for storage of any type of object. To get a pointer to a type other than void, 


use a type cast on the return value. 


In large data models (compact-, large-, and huge-model programs), malloc maps 


to _fmalloc. In small data models (tiny-, small-, and medium-model programs), 


malloc maps to _nmalloc. The _fmalloc function allocates a memory block of at 


least size bytes in the far heap, which is outside the default data segment. 


The _ bmalloc function allocates a memory block of at least size bytes in the based 


heap segment specified by the segment selector seg. 
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The malloc functions allocate memory in the heap segment specified below: 


Function 


malloc 

_bmalloc 
_fmalloc 
_nmalloc 


Heap Segment 


Depends on data model of program 

Based heap segment specified by seg value 
Far heap (outside default data segment) 
Near heap (within default data segment) 


The functions listed below call the malloc family of routines. In addition, the 
startup code uses malloc to allocate storage for the environ/envp and argv strings 


and arrays. 


The following routines call malloc: 


calloc 
_execv 
_execve 
_execvp 
_execvpe 
_execl 
_execle 
_execlp 
_execlpe 
fgetc 
_fgetchar 
fgets 
fprintf 
fputc 
_fputchar 
fputs 
fread 
fscanf 


fseek 
fsetpos 
_fullpath 
fwrite 
getc 
getchar 

_ getcwd 
_getdcwd 
gets 

_ getw 

_ popen 
printf 
pute 
putchar 
_putenv 
puts 
_putw 
_Searchenv 


The following routines call _nmalloc: 


_nrealloc 
_ncalloc 
_nstrdup 


realloc (in small data models) 


_spawnv 
_Spawnve 
_Spawnvp 
_Spawnvpe 
_Spawnl 
_Spawnle 
_spawnlp 
_spawnlpe 
_strdup 
system 
scanf 
setvbuf 
_tempnam 
ungetc 
vfprintf 
vprintf 


Return Value 


Compatibility 


See Also 
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The following routines call _ fmalloc: 


_frealloc 

_fcalloc 

_fstrdup 

realloc (in large data models) 


In Microsoft C version 5.1, the _ fmalloc function would retry allocating within 
the default data segment (1.e., in the near heap) if sufficient memory was not avail- 
able outside the default data segment. Since version 6.0, _ fmalloc returns NULL 
under these conditions. 


The _freect, _memavl, and _memmax functions called malloc in Microsoft C 
version 5.1 but do not do so in versions 6.0 and 7.0. 


The malloc function returns a void pointer to the allocated space. The _nmalloc 
function returns a ( void __near * ) and _fmalloc returns a ( void __ far * ). The 
_bmalloc function returns a ( void __ based( void ) * ). 


The _ malloc, _fmalloc, and _nmalloc functions return NULL if there is insuffi- 
cient memory available. The _ bmalloc function returns _NULLOFF if there is in- 
sufficient memory available. 


Always check the return from the malloc function, even if the amount of memory 
requested is small. 


malloc 

Standards: ANSI, UNIX 

16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X | 


_bmalloc, _ fmalloc, _nmalloc 


Standards: None 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: None 


calloc functions, free functions, realloc functions 
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Example /* MALLOC.C: This program allocates memory with malloc, then frees 
* the memory with free. 
* / 


dFinclude <stdlib.h> /* Definition of _MAX PATH */ 
dAinclude <stdio.h> 
dAinclude <malloc.h> 


void main( void ) 
{ 
char *string; 


/* Allocate space for a path name */ 
string = malloc( _MAX_PATH ); 
if( string == NULL ) 
printf( "Insufficient memory available\n" ); 
else 
printf( "Memory space allocated for pathname\n" ); 
free( string ); 
printf( "Memory freed\n" ); 


Output Memory space allocated for pathname 
Memory freed 
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_matherr, _matherrl 


Description Handle math errors. 
#include <math.h> | 


int _matherr( struct _ exception *except ); 


int _matherrl( struct _ exceptionl “except ); 


except Pointer to structure containing error information 


Remarks The _matherr functions process errors generated by the functions of the math 
library. The math functions call the appropriate _ matherr routine whenever an 
error is detected. The _matherrl function uses the 80-bit, 10-byte coprocessor 
form of arguments and return values. See the reference page on the long double 
functions for more details on this data type. 


The user can provide a different definition of the _matherr or _matherrl func- 
tion to carry out special error handling. 


When an error occurs in a math routine, _matherr is called with a pointer to an 
_ exception type structure (defined in MATH.H) as an argument. 


The _ exception structure contains the following elements: 


Element Description 

int type Exception type 

char *name Name of function where error occurred 
double arg1, arg2 First and second (if any) argument to function 
double retval Value to be returned by function 


The type specifies the type of math error. It is one of the following values, defined 


in MATH.H: 

Value Meaning 

—~DOMAIN Argument domain error 
_SING Argument singularity 
_OVERFLOW Overflow range error 


_PLOSS Partial loss of significance 
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Return Value 


Compatibility 


See Also 


Example 


/* 
* 
* 
* 


* / 


Value Meaning 
_TLOSS Total loss of significance 
_UNDERFLOW Underflow range error 


The structure member name is a pointer to a null-terminated string containing the 
name of the function that caused the error. The structure members arg] and arg2 
specify the values that caused the error. (If only one argument is given, it is stored 
in arg1.) 


The default return value for the given error is retval. If you change the return 
value, remember that the return value must specify whether an error actually oc- 
curred. If the _matherr function returns 0, an error message can be displayed and 
errno is set to an appropriate error value. If _matherr returns a nonzero value, no 
error message 1s displayed, and errno remains unchanged. 


The _matherr functions should return 0 to indicate an error, and a nonzero value 
to indicate successful corrective action. 


_matherr 

Standards: UNIX 

16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 


Use _matherr for compatibility with ANSI naming conventions of non-ANSI 
functions. Use matherr and link with OLDNAMES.LIB for UNIX compatibility. 


_matherrl 
Standards: None 


16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: None 


acos functions, asin functions, atan functions, bessel functions, _ cabs, cos func- 
tions, exp, _hypot, log functions, pow, sin functions, sqrt, tan functions 


MATHERR.C: To use _matherr, you must turn off the Extended Dictionary 
flag within the Microsoft Programmer's WorkBench environment, or use the 
/NOE linker option outside the environment. For example: 


CL _matherr.c /link /NOE 


d#Finclude <math.h> 
#Hinclude <string.h> 
#Hinclude <stdio.h> 


Output 


_matherr, _ matherr! 


void main( void ) 


{ 
/* Do several math operations that cause errors. The _matherr 
* routine handles _DOMAIN errors, but lets the system handle 
* other errors normally. 
* / 
printf( “log( -2.0 ) = Ze\n", log( -2.@ ) ); 
printf( "logl1@( -5.@ ) = Ze\n", 1og1@( -5.@ ) ); 
printf( “log( @.@ ) = Ze\n", log( 0.0 ) ); 
} 


/* Handle several math errors caused by passing a negative argument 

* to log or log1@ (_DOMAIN errors). When this happens, _matherr returns 
* the natural or base-1@ logarithm of the absolute value of the 

* argument and suppresses the usual error message. 


* / 
int _matherr( struct _exception *except ) 
{ 
/* Handle _DOMAIN errors for log or 10g10. */ 
if( except->type == _DOMAIN ) 
{ 
if( strcmp( except->name, “log” == Q@ ) 
{ 


except->retval = log( -(except->argl) ); 


printf( "Special: using absolute value: %s: _DOMAIN error\n", 


except->name ); 


return 1; 
} 
else if( strcmp( except->name, "logl1@" ) == Q@ ) 
{ 
except->retval = logl@( -(except->argl) ); 
printf( "Special: using absolute value: %s: _DOMAIN error\n", 
except->name ); 
return 1; 
} 
} 
else 
printf( "Normal: " ); 
return Q; /* Else use the default actions */ 
} 


Special: using absolute value: log: _DOMAIN error 
log( -2.@ ) = 6.931472e-001 

Special: using absolute value: log1@: _DOMAIN error 
logl@( -5.@ ) = 6.989700e-001 

Normal: log: _SING error 

log( @.@ ) = -1.797693e+308 
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Description 


Remarks 


Return Value 


Compatibility 


See Also 


max 


Returns the larger of two values. 


#include <stdlib.h> 


type __max( type a, type b ); 


type Any numeric data type 


a, b Values of any numeric type to be compared 


The ___max macro compares two values and returns the value of the larger one. 
The arguments can be of any numeric data type, signed or unsigned. Both argu- 
ments and the return value must be of the same data type. 


The macro returns the larger of the two arguments. 


Standards: None 


16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 
__min 


Example /* MINMAX.C */ 
dFinclude <stdlib.h> 
#Hinclude <stdio.h> 


void main( void ) 


{ 
int a = 10; 
int. b =-21% 
printf( "The larger of 4d and %d is %d\n", a, b, max( a, Db) ); 
printf( "The smaller of %d and %d is %4d\n", a, b, NV Sag: UD) 2 
} 
Output The larger of 10 and 21 is 21 


The smaller of 1@ and 21 is 10 


Description 


Remarks 


Return Value 


Compatibility 


See Also 
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mblen, _fmblen 


Get the length and determine the validity of a multibyte character. 
#include <stdlib.h> 


int mblen( const char *mbstr, size_t count )3 


int __ far _fmblen(const char __ far *mbstr, size_t count ); 


mbstr The address of a sequence of bytes (a multibyte 
character) 
count The number of bytes to check 


The mblen function returns the length in bytes of a valid multibyte character. It ex- 
amines count or fewer bytes contained in mbstr. It will not examine more than 
MB_CUR_ MAX bytes. 


The _fmblen function is a model-independent (large-model) form of the mblen 
function. 


If mbstr is not NULL, both mblen and _ fmblen return the length, in bytes, of the 
multibyte character. If mbstr is NULL, or the object that it points to is the wide- 
character null character (L’\0’), both functions return 0. If the object that mbstr 
points to does not form a valid multibyte character within the first count charac- 
ters, both functions return —1. 


mblen 

Standards: ANSI 

16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 

_fmblen 


Standards: None 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: None 


mbstowcs, mbtowc, westombs, wctomb, MB_CUR_MAX, MB_LEN_MAX 
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Example 


Output 


mblen, _fmblen 


/* MBLEN.CPP illustrates the behavior of the mblen function. */ 


#Hinclude <stdlib.h> 
dHinclude <stdio.h> 


void main( void ) 


{ 
int 1; 
char *xpmbc = (char *)malloc( sizeof( char ) ); 
wchar_t~ we = leas 
printf( "Convert a wide character to multibyte character:\n" ); 
7 = wctomb( pmbc, wc ); 
printf( "\tCharacters converted: %4u\n", i ); 
printf( "\tMultibyte character: %x\n\n", pmbc ); 
printf( “Find length--in bytes--of multibyte character:\n" ); 
j = mblen( pmbc, MB_CUR_MAX ); 
printf( "\tLength--in bytes--of multibyte character: Z%u\n", i ); 
printf( "\tWide character: %x\n\n", pmbc ); 
printf( "Attempt to find length of a NULL pointer:\n" ); 
pmbc = NULL; 
i = mblen( pmbc, MB_CUR_MAX ); 
printf( "\tLength--in bytes--of multibyte character: %u\n", i ); 
printf( "\tWide character: %x\n\n", pmbc ); 
printf( "Attempt to find length of a wide-character NULL:\n" ); 
we = L'\@'; 
wctomb( pmbc, wc ); 
i = mblen( pmbc, MB_CUR_MAX ); 
printf( "\tLength--in bytes--of multibyte character: Zu\n", i ); 
printf( "\tWide character: %x\n", pmbc ); 
i 


Convert a wide character to multibyte character: 
Characters converted: 1 
Multibyte character: e56 


Find length--in bytes--of multibyte character: 
Length--in bytes--of multibyte character: 1 
Wide character: e56 


Attempt to find length of a NULL pointer: 
Length--in bytes--of multibyte character: Q 
Wide character: Q 


Attempt to find length of a wide-character NULL: 
Length--in bytes--of multibyte character: @ 
Wide character: @Q 


Description 


Remarks 


Return Value 
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mbstowcs, fmbstowcs 


Convert a sequence of multibyte characters to a corresponding sequence of wide 
characters. 


#include <stdlib.h> 


size_t mbstowcs( wchar_t *wcstr, const char *mbstr, size_t count )3 


size_t __far _fmbstowcs(wchar_t __far *“wcstr, const char __ far *mbstr, 
size_t count ); 


westr The address of a sequence of wide characters 
mbstr The address of a sequence of multibyte characters 
count The number of multibyte characters to convert 


The mbstowcs function converts count or fewer multibyte characters pointed to by 
mbstr to a string of corresponding wide characters that are determined by the cur- 
rent locale. It stores the resulting wide-character string at the address represented 
by westr. The result is similiar to a series of calls to the mbtowe function. 


If mbstowcs encounters the null character (’\0’) either before or when count oc- 
curs, it converts the null character to a wide-character null character (L’\0’) and 
stops. Thus, the wide-character string at westr is null-terminated only if a null char- 
acter is encountered during conversion. If the sequences pointed to by westr and 
mbstr overlap, the behavior is undefined. 


The _fmbstowes function is a model-independent (large-model) form of the 
mbstowes function. It can be called from any point in any program. 


If mbstowcs or (_fmbstowcs) successfully converts the source string, it returns 
the number of converted multibyte characters. If either function encounters an 
invalid multibyte character, it returns —1. If the return value is count, the wide- 
character string 1s not null-terminated. 
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Compatibility mbstowcs 
Standards: ANSI 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 
_fmbstowcs 


Standards: None 


16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: None 
See Also mblen, mbtowc, wcstombs, wctomb, MB_CUR_MAX, MB_LEN_MAX 


Example /* MBSTOWCS.CPP illustrates the behavior of the mbstowcs function. */ 


#Hinclude <stdlib.h> 
dtinclude <stdio.h> 


void main( void ) 


{ 
mg comm be 
char *pmbhello = (char *)malloc( MB_CUR_MAX ); 
wchar_t *pwchello = L"Hi"; 
wchar_t *pwc = (wchar_t *)malloc( sizeof( wchar_t )); 
printf( "Convert to multibyte string:\n" ); 
7 = wcstombs( pmbhello, pwchello, MB _CUR_MAX ); 
printf( "\tCharacters converted: 4u\n", i ); 
printf( "\tHex value of first" ); 
printf( " multibyte character: %#.4x\n\n", pmbhello ); 
printf( "Convert back to wide-character string:\n" ); 
7 = mbstowcs( pwc, pmbhello, MB_CUR_MAX ); 
printf¢( "\tCharacters converted: “4u\n", i ); 
printf( "\tHex value of first" ); 
printf( " wide character: %#.4x\n\n", pwc ); 

} | 

Output Convert to multibyte string: 


Characters converted: 1 
Hex value of first multibyte character: Q@x@e26 


Convert back to wide-character string: 
Characters converted: 1 
Hex value of first wide character: @x@e2a 


Description 


Remarks 


Return Value 


Compatibility 
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mbtowc, _fmbtowc 


Convert a multibyte character to a corresponding wide character. 
#include <stdlib.h> 


int mbtowc( wchar_t *wchar, const char *mbchar, size_t count ); 


int ___ far _fmbtowec(wchar_t __ far *wchar, const char __ far *mbchar, 
size_t count ); 


wchar The address of a wide character (type wchar_t) 

mbchar The address of a sequence of bytes (a multibyte 
character) 

count The number of bytes to check 


The mbtowc function converts count or fewer bytes pointed to by mbchar, if 
mbchar is not NULL, to a corresponding wide character that is determined by the 
current locale. It stores the resulting wide character at wchar, if wchar is not 
NULL. It will not examine more than MB_CUR_ MAX bytes. 


The _fmbtowc function is a model-independent (large-model) form of the 
mbtowc function. 


If mbchar is not NULL and if the object that mbchar points to forms a valid multi- 
byte character, both mbtowc and _fmbtowc return the length in bytes of the multi- 
byte character. 


If mbchar is NULL or the object that it points to is a wide-character null character 
(L’\0’), both functions return 0. If the object that mbchar points to does not form a 
valid multibyte character within the first count characters, they return —1. 


mbtowc 
Standards: ANSI 
16-Bit: DOS, QWIN, WIN, WIN DLL 


32-Bit: DOS32X 
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_fmbtowc 


Standards: None 


16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: None 
See Also mblen, mbtowc, westombs, wctomb, MB_CUR_MAX, MB_LEN_MAX 


Example /* MBTOWC.CPP illustrates the behavior of the mbtowc function. */ 


d#FAinclude <stdlib.h> 
dEinclude <stdio.h> 


void main( void ) 


{ 
Tmt is 
char *pmbC = (char *)malloc( sizeof( char ) ); 
wchar_t wc = Eas 
wchar_t *pwcnull = NULL; 


wchar_t *pwc (wchar_t *)malloc( sizeof( wchar_t ) ); 


printf( "Convert a wide character to multibyte character:\n" ); 
i = wctomb( pmbc, wc ); 

printf( "\tCharacters converted: 4u\n", i ); 

printf( "\tMultibyte character: %x\n\n", pmbc ); 


printf( "Convert multibyte character back to a wide character:\n" ); 
| = mbtowc( pwc, pmbc, MB_CUR_MAX ); 

printf( "\tBytes converted: %u\n", i ); 

printf( "\tWide character: %x\n\n", pwc ); 


printf( “Attempt to convert when target is NULL\n" ); 

printf( " returns the length of the multibyte character:\n" ); 
j = mbtowc( pwcnull, pmbc, MB_CUR_MAX ); 

printf( "\tLength of multibyte character: %u\n\n", i ); 


printf( "Attempt to convert a NULL pointer to a” ); 
printf( " wide character:\n" ); 

pmbc = NULL; 

7 = mbtowc( pwc, pmbc, MB_CUR_MAX ); 

printf( "\tBytes converted: %u\n", i ); 


Output 


mbtowc, _fmbtowc 


Convert a wide character to multibyte character: 
Characters converted: 1 
Multibyte character: e36 


Convert multibyte character back to a wide character: 
Bytes converted: 1 
Wide character: e3a 


Attempt to convert when target is NULL 
returns the length of the multibyte character: 
Length of multibyte character: 1 


Attempt to convert a NULL pointer to a wide character: 
Bytes converted: Q 
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Description 


Remarks 


Return Value 


Compatibility 


See Also 


_memavl 


Returns the size of memory available. 
#include <malloc.h> Required only for function declarations 


size_t _memavl( void ); 


The _memavl function returns the approximate size, in bytes, of the memory 
available for dynamic memory allocation in the near heap (default data segment). 
The _memavl function can be used with calloc, malloc, or realloc in tiny, small, 
and medium memory models and with _ncalloc, _nmalloc or _nrealloc in any 
memory model. 


The number returned by the _memavl function may not be the number of contigu- 
ous bytes. Consequently, a call to malloc requesting allocation of the size returned 
by _memavl may not succeed. Use the _memmax function to find the size of the 

largest available contiguous block of memory. 


The _memavl function returns the size in bytes as an unsigned integer. 


Standards: None 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: None 


calloc functions, _freect, malloc functions, _memmakx, realloc functions 


Example /* MEMAVL.C: This program uses _memavl to determine the amount of 
* memory available for dynamic allocation. It then uses malloc to 
* allocate space for 5,000 long integers and uses _memavl again to 
* determine the new amount of available memory. 


* / 


dHinclude <malloc.h> 
dFinclude <stdio.h> 
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void main( void ) 


{ 
long *longptr; 
printf( “Memory available before _nmalloc = %u\n", _memavl() ); 
if( (longptr = _nmalloc( 5000 * sizeof( long ) )) != NULL ) 
{ 
printf( "Memory available after _nmalloc = Z4u\n", _memavl() ); 
_nfree( longptr ); 
} 
I 
Output Memory available before _nmalloc = 60906 


Memory available after _nmalloc = 40390 
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_memccpy, _fmemccpy 


Description Copy characters from a buffer. 
#include <memory.h> Required only for function declarations 
#include <string.h> Use either STRING.H or MEMORY.H 


void *_memccpy( void *dest, void *src, int c, unsigned int count ); 


void __far * ___ far _fmemccpy( void __far “dest, void __far *src, int c, 
unsigned int count ); 


dest Pointer to destination 
STC Pointer to source 
C Last character to copy 
count Number of characters 
Remarks The _memccpy and _fmemccpy functions copy 0 or more bytes of src to dest, 


halting when the character c has been copied or when count bytes have been 
copied, whichever comes first. 


The _fmemcepy function is a model-independent (large-model) form of the 
_memccpy function. It can be called from any point in any program. 


Return Value If the character c is copied, _memccpy or _fmemccpy returns a pointer (or far 
pointer) to the byte in dest that immediately follows the character. If c is not 
copied, both return NULL. 


Compatibility _memccpy 
Standards: UNIX 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 


Use _memccpy for compatibility with ANSI naming conventions of non-ANSI 
functions. Use memccpy and link with OLDNAMES.LIB for UNIX compatibility. 


See Also 


Example 


Output 


_memccpy, _fmemccpy 497 


_fmemccpy 


Standards: None 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: None 


memchr, memcmp, memcpy, memset 


/* MEMCCPY.C */ 
#Hinclude <memory.h> 
#Hinclude <stdio.h> 
d#Finclude <string.h> 


char stringl1[60] = "The quick brown dog jumps over the lazy fox"; 


void main( void ) 


4 

char buffer[61]; 

char *pdest; 

printf( "Function:\t_memccpy 6@ characters or to character ‘s'\n" ); 

printf( “Source:\t\t%s\n", stringl ); 

pdest = _memccpy( buffer, stringl, 's', 60 ); 

*pdest = ‘'\Q'; 

printf( "Result:\t\t%s\n", buffer ); 

printf( “Length:\t\t%d characters\n\n", strlen( buffer ) ); 
} 
Function: _memccpy 6@ characters or to character 's' 
Source: The quick brown dog jumps over the lazy fox 
Result: The quick brown dog jumps 


Length: 25 characters 
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Description 


Remarks 


Return Value 


Compatibility 


See Also 


memehr, _fmemchr 


Find characters in a buffer. 


#include <memory.h> Required only for function declarations 
#include <string.h> Use either STRING.H (for ANSI compatibility) or 
MEMORY .H 


void *memchr( const void *buf, int c, size_t count ); 


void __ far * ___ far _fmemchr( const void __ far *buf, int c, size_t count ); 


buf Pointer to buffer 
C | Character to look for 
count Number of characters 


The memchr and _ fmemchr functions look for the first occurrence of c in the 
first count bytes of buf. They stop when they find c or when they have checked the 
first count bytes. 


The _fmemchr function is a model-independent (large-model) form of the 
memcehr function. It can be called from any point in any program. 


If successful, memchr or _fmemchr returns a pointer (or a far pointer) to the first 
location of c in buf. Otherwise, they return NULL. 


memchr 

Standards: ANSI, UNIX 

16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 

_fmemchr 


Standards: None 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: None 


_memccpy, memcmp, memcpy, memset, strchr 


Example 


Output 


/* MEMCHR.C */ 


memchr, _fmemechr 


dtinclude <memory.h> 
#Hinclude <stdio.h> 


TN. 26h Fs 
Char str] = 
char stringL] = 
char fmtl1[] 
char fmt2[] 


void main( void 
{ 
char *pdest; 
int result; 


hazy: 

"The quick brown dog jumps over the lazy fox"; 

7 1 2 S 4 oS 
"12345678901234567890123456789012345678901234567890"; 


) 


printf( "String to be searched:\n\t\t%s\n", string ); 
printf( "\t\t%s\n\t\t%s\n\n", fmtl, fmt2 ); 


printf( "Search char:\t%c\n", ch ); 
pdest = memchr( string, ch, sizeof( string ) ); 
result = pdest - string + 1; 


if( pdest != 


NULL ) 


printf( “Result:\t\t%c found at position %d\n\n", ch, result ); 


else 


printf( "Result:\t\t%c not found\n" ); 


String to be searched: 


Search char: 
Result: 


The quick brown dog jumps over the lazy fox 
1 2 3 4 5 
12345678901234567890123456789012345678901234567890 


r 
r found at position 12 
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Description 


Remarks 


Return Value 


mememp, _fmememp 


Compare characters in two buffers. 


#include <memory.h> Required only for function declarations 
#include <string.h> Use either STRING.H (for ANSI compatibility) or 
MEMORY .H 


int memcmp( const void *bufl, const void *buf2, size_t count ); 


int __ far _fmemcmp( const void __ far *buf/, const void __ far *buf2, 
size_t count ); 


buf] First buffer 
buf2 | Second buffer 
count Number of characters 


The memecmp and _fmememp functions compare the first count bytes of buf] 
and buf2 and return a value indicating their relationship, as follows: 


Value Meaning 

<0 buf] less than buf2 
=0 buf] identical to buf2 
>0 bufl greater than buf2 


The _fmememp function is a model-independent (large-model) form of the 
memcmp function. It can be called from any point in a program. 


There is a semantic difference between the function version of memcmp and its in- 
trinsic version. The function version supports huge pointers in compact-, large-, 
and huge-model programs, but the intrinsic version does not. 


The memcmp and _fmemcmp functions return an integer value, as described 
above. 


memcmp, fmememp 501 


Compatibility memcmp 
Standards: ANSI, UNIX 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 
_fmemcmp 


Standards: None 


16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: None 
See Also _memccpy, memchr, memcpy, memset, strcmp, strncmp 


Example /* MEMCMP.C: This program uses memcmp to compare the strings named 
* first and second. If the first 19 bytes of the strings are 
* equal, the program considers the strings to be equal. 
a / 


#Hinclude <string.h> 
#Hinclude <stdio.h> 


void main( void ) 

{ 
char first] "1234567890123456/7890"; 
char second£] = "12345678901234567891"; 
int result; 


printf( "Compare '%.19s' to '%.19s':\n", first, second ); 
result = memcmp( first, second, 19 ); 
if( result < @ ) 
printf( "First is less than second.\n" ); 
else if( result == @ ) 
printf( "First is equal to second.\n" ); 
else if( result > @ ) 
printf( "First is greater than second.\n" ); 
printf( "Compare '%.2@s' to '%.20s':\n", first, second ); 
result = memcmp( first, second, 20 ); 
if( result < @ ) 
printf( "First is less than second.\n" ); 
else if( result == @ ) 
printf( "First is equal to second.\n" ); 
else if( result > @ ) 
printf( "First is greater than second.\n" ); 
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Output Compare '1234567890123456789' to '1234567890123456789': 
First is equal to second. 
Compare '12345678901234567890' to '1234567890123456/7891': 
First is less than second. 


Description 


Remarks 


Return Value 


Compatibility 
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memcpy, _fmemepy 


Copy characters between buffers. 


#include <memory.h> Required only for function declarations 
#include <string.h> Use either STRING.H (for ANSI compatibility) or 
MEMORY .H 


void *memcpy( void *dest, const void *src, size_t count ); 


void __far *__far _fmemcpy( void __far “dest, const void __ far *src, 
size_t count ); 


dest New buffer 
STC Buffer to copy from 
count Number of characters to copy 


The memcpy and _fmemcpy functions copy count bytes of src to dest. If the 
source and destination overlap, these functions do not ensure that the original 
source bytes in the overlapping region are copied before being overwritten. Use 
memmove to handle overlapping regions. 


The _fmemcpy function is a model-independent (large-model) form of the 
memcpy function. It can be called from any point in any program. 


There is a semantic difference between the function version of memcpy and its in- 
trinsic version. The function version supports huge pointers in compact-, large-, 
and huge-model programs, but the intrinsic version does not. 


The memcpy and _fmemcpy functions return the value of dest. 


memcpy 
Standards: ANSI, UNIX 
16-Bit: DOS, QWIN, WIN, WIN DLL 


32-Bit: DOS32X 
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_fmemcpy 


Standards: None 


16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: None 
See Also _memccpy, memchr, memcmp, memmove, memset, strcpy, strncpy 


Example /* MEMCPY.C. Illustrate overlapping copy: memmove handles it 
* correctly; memcpy does not. 
* / 


d4Ainclude <memory.h> 
#Finclude <string.h> 
d#Ainclude <stdio.h> 


char stringl[60] "The quick brown dog jumps over the lazy fox"; 
char string2[60] = "The quick brown fox jumps over the lazy dog"; 


/* 1 2 3 4 3 
** 12345678901234567890123456/89012345678901234567890 
* / 


void main( void ) 
{ 
printf( "Function:\tmemcpy without overlap\n" ); 
printf( "Source:\t\t%s\n", stringl + 4@ ); 
printf( "Destination: \t%s\n", stringl + 16 ); 
memcpy( stringl + 16, stringl + 40, 3 ); 
printf( "Result:\t\t%s\n", stringl ); 
printf( "Length:\t\t%d characters\n\n", strlen( stringl ) ); 


/* Restore stringl to original contents */ 
memcpy( stringl + 16, string2 + 40, 3 ); 


printf( "Function:\tmemmove with overlap\n" ); 

printf( "Source:\t\t%s\n", string2 + 4 ); 

printf( "Destination:\t%s\n", string2 + 10 ); 

memmove( string2 + 10, string2 + 4, 4@ ); 

printf( "Result:\t\t%s\n", string2 ); 

printf( "Length:\t\t%d characters\n\n", strlen( string2 ) ); 


printf( "Function:\tmemcpy with overlap\n" ); 

printf( "Source:\t\t%s\n", stringl + 4 ); 

printf( "Destination:\t%s\n", stringl + 10 ); 

memcpy( stringl + 10, stringl + 4, 4@ ); 

printf( "Result:\t\t%s\n", stringl ); 

printf( "Length:\t\t%d characters\n\n", strlen( stringl ) ); 


Output 


Function: 
Source: 


Destination: 


Result: 
Length: 


Function: 
Source: 


Destination: 


Result: 
Length: 


Function: 
Source: 


Destination: 


Result: 
Length: 


memcpy, _fmemcpy 


memcpy without overlap 

fox 

dog jumps over the lazy fox 

The quick brown fox jumps over the lazy fox 
43 characters 


memmove with overlap 

quick brown fox jumps over the lazy dog 

brown fox jumps over the lazy dog 

The quick quick brown fox jumps over the lazy dog 
49 characters 


memcpy with overlap 

quick brown dog jumps over the lazy fox 

brown dog jumps over the lazy fox 

The quick quick quick quick quick quick quick quick 
5@ characters 
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506 _memicmp, _fmemicmp 


Description 


Remarks 


Return Value 


_memicmp, _fmemicmp 


Compare characters in two buffers (case-insensitive). 


#include <memory.h> Required only for function declarations 
#include <string.h> Use either STRING.H or MEMORY.H 


int _memicmp( void *buf1], void *buf2, unsigned int count ); 


int __far _fmemicmp( void __ far *buf1, void __far *buf2, 
unsigned int count ); 


buf First buffer 
buf2 Second buffer 
count Number of characters 


The _memicmp and _fmemicmp functions compare the first count characters of 
the two buffers buf] and buf2 byte-by-byte. The comparison is made without re- 
gard to the case of letters in the two buffers; that is, uppercase and lowercase let- 
ters are considered equivalent. The _memicmp and _fmemicmp functions return 
a value indicating the relationship of the two buffers, as follows: 


Value Meaning 

<0 buf] less than buf2 

= 0 buf1 identical to buf2 
> 0 buf] greater than buf2 


The _fmemicmp function is a model-independent (large-model) form of the 
_memicmp function. It can be called from any point in any program. 


The _memicmp and _fmemicmp functions return an integer value, as described 
above. 


Compatibility 


See Also 


Example 


Output 


_memicmp, _fmemicmp 


_memicmp 

Standards: UNIX 

16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 


Use _memicmp for compatibility with ANSI naming conventions of non- 
ANSI functions. Use memicmp and link with OLDNAMES.LIB for UNIX 


compatibility. 
_fmemicmp 


Standards: None 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: None 


_memccpy, memchr, memcmp, memcpy, memset, _ stricmp, _ strnicmp 


/* MEMICMP.C: This program uses _memicmp to compare the first 


* 29 letters of the strings named first and second without 
* regard to the case of the letters. 


#Hinclude <memory.h> 
fHinclude <stdio.h> 
fHinclude <string.h> 


void main( void ) 


{ 


int result; 

char firstL] = "Those Who Will Not Learn from History"; 

char secondlL] = "THOSE WHO WILL NOT LEARN FROM their mistakes"; 
/* Note that the 29th character is right here * */ 


printf( "Compare '%.29s' to '%.29s'\n", first, second ); 
result = _memicmp( first, second, 29 ); 
if( result < @ ) 
printf( "First is less than second.\n" ); 
else if( result == @ ) 
printf( "First is equal to second.\n" ); 
else if( result > @ ) 
printf( "First is greater than second.\n" ); 


Compare ‘Those Who Will Not Learn from" to ‘THOSE WHO WILL NOT LEARN 
First 1S equal to second. 


FROM" 
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908 _memmax 


Description 


Remarks 


Return Value 


Compatibility 


See Also 


_memmax 


Finds the size of the largest contiguous memory block. 
#include <malloc.h> 


size_t _memmax( void ); 


The _memmakx function returns the size (in bytes) of the largest contiguous block 
of memory that can be allocated from the near heap (1.e., the default data seg- 
ment). Calling _ nmalloc with the value returned by the _ memmax function will 
succeed as long as _memmakx returns a nonzero value. 


The function returns the block size, if successful. Otherwise, it returns 0, indicat- 
ing that nothing more can be allocated from the near heap. 


Standards: None 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: None 


malloc functions, _msize functions 


Example /* MEMMAX.C: This program uses _memmax and _nmalloc to allocate 
* the largest block of memory available in the near heap. 


* / 


#Hinclude <stddef.h> 
d#Ainclude <malloc.h> 
d4Finclude <stdio.h> 


void main( void ) 


{ 


size_t contig; 


char 


*D; 


_ memmax 909 


/* Determine contiguous memory size */ 

contig = _memmax(); 

printf( “Largest block of available memory is %u bytes long\n", contig ); 
if( contig ) 


{ 
p = _nmalloc( contig * sizeof( int ) ); 
iar. (pes NUE 
printf( “Error with malloc (should never occur)\n" ); 
else 
{ 
printf( "Maximum allocation succeeded\n" ); 
free( p ); 
} 
} 
else 
printf( "Near heap is already full\n" ); 
} 
Output Largest block of available memory is 60844 bytes long 


Maximum allocation succeeded 


510 memmove, _fmemmove 


Description 


Remarks 


Return Value 


Compatibility 


See Also 


memmove, _fmemmove 


Move one buffer to another. 
#include <string.h> 
void *memmove( void *dest, const void *s7rc, size_t count ); 


void __ far * ___ far _fmemmove( void __ far “dest, const void __far *src, 
size_t count ); 


dest Destination object 
STC Source object 
count Number of characters to copy 


The memmove and _fmemmove functions copy count characters from the source 
(src) to the destination (dest). If some regions of the source area and the destina- 
tion overlap, the memmove and _fmemmove functions ensure that the original 
source bytes in the overlapping region are copied before being overwritten. 


The _fmemmove function is a model-independent (large-model) form of the 
memmove function. It can be called from any point in any program. 


The memmove and _fmemmove functions return the value of dest. 


memmove 
Standards: ANSI 

16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 

_fmemmove 


Standards: None 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: None 


_memccpy, memcpy, strcpy, strncpy 


Example 


memmove, _fmemmove 


/* MEMCPY.C. Illustrate overlapping copy: memmove handles it 
* correctly; memcpy does not. 


* / 


#Hinclude <memory.h> 
#Hinclude <string.h> 
#Hinclude <stdio.h> 


char stringl[60] 
char string2L60] 


/* 


* 


* / 


void main( 


{ 


printf ( 
printf ( 
printf ( 
memcpy ( 
printf ( 
printf ( 


"The quick brown dog jumps over the lazy fox"; 
"The quick brown fox jumps over the lazy dog"; 

1 2 3 4 5 
12345678901234567890123456789012345678901234567890 


void ) 


"Function: \tmemcpy without overlap\n" ); 
"Source:\t\t%s\n", stringl + 40 ); 

"Destination: \t%s\n", stringl + 16 ); 

stringl + 16, stringl + 40, 3 ); 

"Result:\t\t%s\n", stringl ); 

"Length:\t\t%d characters\n\n", strlen( stringl ) ); 


/* Restore stringl to original contents */ 


memcpy ( 


printf ( 
printf ( 
printf ( 


stringl + 16, string2 + 40, 3°); 


"Function: \tmemmove with overlap\n" ); 
“SOURCES\EVL SSN 5 SLPINgGZ + 44% 
"Destination: \t%s\n", string2 + 10 ); 


memmove( string2 + 10, string2 + 4, 40 ); 


printf ( 
printf ( 


printf ( 
printf ( 
printf ( 
memcpy ( 
printf ( 
printf ( 


"Result: \t\t%s\n", string2 ); 
"Length: \t\t%d characters\n\n", strlen( string2 ) ); 


"Function: \tmemcpy with overlap\n" ); 
"Source:\t\t%s\n", stringl + 4 ); 

"Destination: \t%s\n", stringl + 10 ); 

stringl + 10, stringl + 4, 4@ ); 

"Result:\t\t%s\n", stringl ); 

"Length: \t\t%d characters\n\n", strlen( stringl ) ); 


o11 
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Output 


Function: 
Source: 


Destination: 


Result: 
Length: 


Function: 
Source: 


Destination: 


Result: 
Length: 


Function: 
Source: 


Destination: 


Result: 
Length: 


memmove, _fmemmove 


memcpy without overlap 


FOX 

dog jumps over the lazy fox 

The quick brown fox jumps over the lazy fox 
43 characters | 


memmove with overlap 

quick brown fox jumps over the lazy dog 

brown fox jumps over the lazy dog 

The quick quick brown fox jumps over the lazy dog 
49 characters 


memcpy with overlap 

quick brown dog jumps over the lazy fox 

brown dog jumps over the lazy fox 

The quick quick quick quick quick quick quick quick 
5@ characters 


Description 


Remarks 


Return Value 


Compatibility 
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memset, _fmemset 


Set buffers to a specified character. 


#include <memory.h> Required only for function declarations 
#include <string.h> Use either STRING.H (for ANSI compatibility) or 
MEMORY .H 


void *memset( void *dest, int c, size_t count ); 


void __ far * __ far _fmemset( void __ far “dest, int c, size_t count ); 


dest Pointer to destination 
C Character to set 
count Number of characters 


The memset and _ fmemset functions set the first count bytes of dest to the charac- 
ter c. 


The _fmemset function is a model-independent (large-model) form of the 
memset function. It can be called from any point in any program. 


There is a semantic difference between the function version of memset and its in- 


trinsic version. The function version supports huge pointers in compact-, large-, 
and huge-model programs, but the intrinsic version does not. 


The memset and _ fmemset functions return the value of dest. 


memset 
Standards: ANSI, UNIX 
16-Bit: DOS, QWIN, WIN, WIN DLL 


32-Bit: DOS32X 


514 memset, _fmemset 


_fmemset 


Standards: None 


16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: None 
See Also _memccpy, memchr, memcmp, memcpy, _ strnset 


Example /* MEMSET.C: This program uses memset to set the first four bytes 
* Of buffer to "*". 
¢ / 


#tinclude <memory.h> 
#tinclude <stdio.h> 


void main( void ) 


char buffer[L] = "This is a test of the memset function"; 
printf( "Before: %s\n", buffer ); 
memset( buffer, '*', 4 ); 
printf( “After: s\n", buffer ); 
} 
Output Before: This is a test of the memset function 


After: **** 7s a test of the memset function 


min 


Description Returns the smaller of two values. 


#include <stdlib.h> 


type __min( type a, type b ); 


min 515 


type Any numeric data type 
a, b Values of any numeric type to be compared 
Remarks The __min macro compares two values and returns the value of the smaller one. 


The arguments can be of any numeric data type, signed or unsigned. Both argu- 
ments and the return value must be of the same data type. 


Return Value The macro returns the smaller of the two arguments. 
Compatibility Standards: None 

16-Bit: DOS, QWIN, WIN, WIN DLL 

32-Bit: DOS32X 
See Also __max 


Example /* MINMAX.C */ 
#Hinclude <stdlib.h> 
#Hinclude <stdio.h> 


void main( 
{ 
int a = 
int b = 
printf ( 
printf ( 
I 
Output The larger 


void ) 


10; 
Yea Ve 


"The larger of %d and %d is %4d\n", a, b 
"The smaller of %d and %d is %d\n", a, b 


of 10 and 21 is 21 


The smaller of 10 and 21 is 10 


516 _ mkdir 


Description 


Remarks 


Return Value 


Compatibility 


See Also 


_ mkdir 


Creates a new directory. 
#include <direct.h> Required only for function declarations 
int _mkdir( char “dirname ); 


dirname Path name for new directory 


The _ mkdir function creates a new directory with the specified dirname. Only 
one directory can be created at a time, so only the last component of dirname can 
name a new directory. 


The _ mkdir function does not do any translation of path-name delimiters. All 
operating systems accept either “\’ or “/” internally as valid delimiters within 
path names. 


The _mkdir function returns the value 0 if the new directory was created. A re- 
turn value of —1 indicates an error, and errno is set to one of the following values: 


Value Meaning 

EACCES Directory not created. The given name is the name of an existing 
file, directory, or device. 

ENOENT Path name not found. 


Standards: None 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 


_chdir, _ rmdir 
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Example /* MAKEDIR.C */ 
dHinclude <direct.h> 
#Hinclude <stdlib.h> 
#Hinclude <stdio.h> 


void main( void ) 


{ 
int result; 
if( _mkdir( “"\\testtmp" ) == @ ) 
{ 
printf( "Directory '\\testtmp' was successfully created\n" ); 
system( "dir \\testtmp" ); 
if( _rmdir( "\\testtmp" ) == @ ) 
printf( "Directory "\\testtmp' was successfully removed\n"  ); 
else 
printf( "Problem removing directory '‘\\testtmp'\n" ); 
} 
else 
printf( "Problem creating directory ‘\\testtmp'\n" ); 
} 
Output Directory '\testtmp’ was successfully created 


The volume label in drive C is ZEPPELIN 
Directory of C:\TESTTMP 


<DIR> 12-19-99 11:20a 
<DIR> 12-19-99 11:2@a 
2 File(s) 12730368 bytes free 
Directory ‘\testtmp' was successfully removed 


518  ##—_mktemp 


Description 


Remarks 


Return Value 


_mktemp 


Creates a unique filename. 
#include <io.h> Required only for function declarations 
char *_mktemp( char “template ); 


template Filename pattern 


The _mktemp function creates a unique filename by modifying the given 
template argument. The template argument has the form: 


baseXXXXXX 


where base is the part of the new filename that you supply, and the X’s are place- 
holders for the part supplied by _mktemp; _mktemp preserves base and replaces 
the six trailing X’s with an alphanumeric character followed by a five-digit value. 
The five-digit value is a unique number identifying the calling process. The alpha- 
numeric character is 0 (’0’) the first time _mktemp is called with a given template. 


In subsequent calls from the same process with copies of the same template, 
_mktemp checks to see if previously returned names have been used to create 
files. If no file exists for a given name, _mktemp returns that name. If files exist 
for all previously returned names, _mktemp creates a new name by replacing the 
alphanumeric character in the name with the next available lowercase letter. For 
example, if the first name returned is t@12345 and this name is used to create a 
file, the next name returned will be ta12345. When creating new names, 
_mktemp uses, in order, ’0’ and then the lowercase letters ’a’ through ’z’. 


Note that the original template is modified by the first call to__mktemp. If you 
then call the _mktemp function again with the same template (1.e., the original 
one), you will get an error. 


The _mktemp function generates unique filenames but does not create or open 
files. 


The _mktemp function returns a pointer to the modified template. The return 
value is NULL if the template argument is badly formed or no more unique names 
can be created from the given template. 


_mktemp 519 


Compatibility Standards: UNIX 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 


See Also 


Example 


Use _mktemp for compatibility with ANSI naming conventions of non-ANSI 
functions. Use mktemp and link with OLDNAMES.LIB for UNIX compatibility. 


fopen, _ getpid, _ open, _ tempnam, tmpfile 


/* MKTEMP.C: The program uses _mktemp to create five unique filenames. 
* It opens each filename to ensure that the next name is unique. 
* / 


dFinclude <io.h> 
#Hinclude <string.h> 
dEinclude <stdio.h> 


Char *template = “fnXXXXXX"; 
char *result; 
char names[5][9]; 


void main( void ) 


{ 
int 1; 
FILE *fp; 
TOR SO Se Op ae) 
{ 
strcpy( names[i], template ); 
/* Attempt to find a unique filename: */ 
result = _mktemp( names[i] ); 
if( result == NULL ) 
printf( "Problem creating the template" ); 
else 
f « 
if( (fp = fopen( result, "w" )) != NULL ) 
printf( "Unique filename is %s\n", result ); 
else 
printf( "Cannot open %s\n", result ); 
fclose( fp ); 
} 
i 
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Output 


_mktemp 


Unique 
Unique 
Unique 
Unique 
Unique 


filename 
filename 
filename 
filename 
filename 


is 
1s 
is 
is 
is 


fn@00686 
fnaQ0686 
fnb@0686 
fnc@0686 
fnd@0686 


Description 


Remarks 


Return Value 


Compatibility 


See Also 


mktime 521 


mktime 


Converts the local time to a calendar value. 
#include <time.h> 
time_t mktime( struct tm *timeptr ); 


timeptr Pointer to time structure 


The mktime function converts the supplied time structure (possibly incomplete) 
pointed to by timeptr into a fully defined structure with “normalized” values and 
then converts it to a time_t calendar time value. The structure for the tm is de- 
scribed in the reference page for asctime. 


The converted time has the same encoding as the values returned by the time func- 
tion. The original values of the tm_wday and tm_yday components of the 
timeptr structure are ignored, and the original values of the other components are 
not restricted to their normal ranges. 


If successful, mktime sets the values of tm_wday and tm_yday appropriately, 
and sets the other components to represent the specified calendar time, but with 
their values forced to the normal ranges; the final value of tm_mday is not set 
until tm_mon and tm_ year are determined. 


If timeptr references a date before midnight, December 31, 1899, mktime 
returns —1. 


Note that the gmtime and localtime functions use a single statically allocated 
buffer for the conversion. If you supply this buffer to mktime, the previous 
contents will be destroyed. 


The mktime function returns the specified calendar time encoded as a value of 
type time_t. If the calendar time cannot be represented, the function returns the 
value —1 cast to type time_t. 


Standards: ANSI 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 


asctime, gmtime, localtime, time 


022 


Example 


Output 


mktime 


/* MKTIME.C: The example takes a number of days as input and returns 
* the time, the current date, and the specified number of days. 
* / 


dEinclude <time.h> 
d#Finclude <stdio.h> 


void main( void ) 


{ 
struct tm when; 
time_t now, result; 
int days; 
time( &now ); 
when = *localtime( &now ); 
printf( "Current time is 4s\n", asctime( &when ) ); 
printf( “How many days to look ahead: " ); 
scanf( "%d", &days ); 
when.tm_mday = when.tm_mday + days; 
if( (result = mktime( &when )) != (time_t)-1 ) 
printf( "In 4d days the time will be %s\n", 
days, asctime( &when ) ); 
else 
perror( "“mktime failed" ); 
} 


Current time is Sat Jun 19 11:45:20 1999 


How many days to look ahead: 23 
In 23 days the time will be Mon Jul 12 11:45:20 1999 


Description 


Remarks 


Return Value 


Compatibility 


See Also 


modf, _modfl 523 


modf, _modfl 


Split a floating-point value into fractional and integer parts. 
#include <math.h> 


double modf( double x, double *intptr ); 


long double _ modfl( long double x, long double “intptr ); 


x Floating-point value 


intptr Pointer to stored integer portion 


The modf functions break down the floating-point value x into fractional and in- 
teger parts, each of which has the same sign as x. The signed fractional portion of 
x is returned. The integer portion is stored as a floating-point value at intptr. 


The _modfl function uses the 80-bit, 10-byte coprocessor form of arguments and 
return values. See the reference page on the long double functions for more details 
on this data type. 


The modf and _ modfl functions return the signed fractional portion of x. There is 
no error return. 


modf 

Standards: ANSI, UNIX 

16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 

_modfl 

Standards: None 

16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: None 


frexp, ldexp 
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Example /* MODF.C */ 
#Finclude <math.h> 
#Hinclude <stdio.h> 


void main( void ) 


{ 

double x, y, n; 

x = -14.87654321; /* Divide x into its fractional */ 

y = modf( x, &n ); /* and integer parts * / 

printf( "For 4f, the fraction is 4f and the integer is %.f\n", x, y, n ); 
} 


Output For -14.876543, the fraction is -@.876543 and the integer is -14 


Description 


Remarks 


Return Value 


Compatibility 


See Also 


_movedata 525 


_movedata 


Moves characters to another segment. 


#include <memory.h> Required only for function declarations 
#include <string.h> Use either STRING.H or MEMORY.H 


void _movedata( unsigned int srcseg, unsigned int srcoff, unsigned int destseg, 
unsigned int destoff, unsigned int count ); 


srcseg Segment address of source 
srcoff Segment offset of source 
destseg Segment address of destination 
destoff Segment offset of destination 
count Number of bytes 


The _movedata function copies count bytes from the source address specified by 
srcseg:srcoff to the destination address specified by destseg:destoff. 


The _movedata function was intended to move far data in small-model programs. 
The newer model-independent _fmemepy and _fmemmove functions should be 
used instead of the _ movedata function. In large-model programs, the memcpy 
and memmove functions can also be used. 


Segment values for the srcseg and destseg arguments can be obtained by using 
either the _segread function or the _FP_SEG macro. 


The _movedata function does not handle all cases of overlapping moves cor- 
rectly. These occur when part of the destination 1s the same memory area as part 
of the source. The memmove function correctly handles overlapping moves. 


None. 


Standards: None 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: None 


_FP_OFF, _FP_SEG, memcpy, memmove, _ segread 
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Example /* MOVEDATA.C */ 
#Finclude <memory.h> 
#Hinclude <stdio.h> 
#Hinclude <string.h> 
#tinclude <dos.h> 
#Hinclude <malloc.h> 


char __far *src = "This is a test."; 


void main( void ) 


{ 
char __far *dest; 
if( (dest = _fmalloc( 8@ )) != NULL ) 
i 
_movedata( _FP_SEG( src ), _FP_OFF( Src ), 

_FP_SEG@( dest ), _FP_OFF( dest ), _fstrlen( src ) + 1 ); 
printf( "The source data at “Fp is '%Fs'\n", src, src ); 
printf( "The destination data at “Fp is '%Fs'\n", dest, dest ); 
_ffree( dest ); 

J 
I 
Output The source data at 2D@A:02B8 is 'This is a test.' 


The destination data at 3DQ0B:0016 is 'This is a test.' 


Description 


Remarks 


Return Value 
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_moveto Functions 


Move current graphics positions. 
#include <graph.h> 


struct _xycoord __ far _moveto( short x, short y ); 


struct _wxycoord __ far _moveto_w( double wx, double wy ); 


x,y View-coordinate point 


wx, wy Window-coordinate point 


The _ moveto functions move the current position to the specified point. The 
_moveto function uses the view-coordinate point (x, y) as the current position. 
The _moveto_ w function uses the window-coordinate point (wx, wy) as the cur- 
rent position. No drawing takes place. 


The _ moveto function operates only in graphics video modes (e.g., 
_MRES4COLOR). Because it is a graphics function, the color of text is set by 
the _setcolor function, not by the _ settextposition function. 


The function returns the coordinates of the previous position. The _moveto func- 
tion returns the coordinates in an _xycoord structure. The _xycoord structure, 
defined in GRAPH.H, contains the following elements: 


Element Description 
short xcoord x coordinate 
short ycoord y coordinate 


The _moveto_w function returns the coordinates in an _ wxycoord structure, de- 
fined in GRAPH.H. The _ wxycoord structure contains the following elements: 


Element Description 


double wx x window coordinate 
double wy y window coordinate 
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Compatibility Standards: None 
16-Bit: DOS 
32-Bit: None 
See Also _lineto functions, _ outgtext 


Example /* MOVETO.C: This program draws line segments of different colors. */ 


#Hinclude <graph.h> 
d#Hinclude <stdlib.h> 
4Finclude <conio.h> 


void main( void ) 

{ 
SROPL X;. “V. KIN,“ yinc, color: =]. 1; 
struct _videoconfig v; 


/* Find a valid graphics mode. */ 

if( !_setvideomode( _MAXCOLORMODE ) ) 
exit( 1 ); 

_getvideoconfig( &v ); 


Xinc = v.numxpixels / 5@; 

yinc = v.numypixels / 50; 

for( x = @, y = v.numypixels - 1; x < v.numxpixels; xX += xinc, y -= yinc ) 
{ 


_setcolor( color++ % 16 ); 
_moveto( x, @ ); 
_lineto( @, y ); 

} 

_getch(); 


_setvideomode( _DEFAULTMODE ); 
exit( @ ); 


Description 


Remarks 


Return Value 
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_msize Functions 


Return the size of a memory block allocated in the heap. 
#include <malloc.h> Required only for function declarations 


size_t _msize( void *memblock ); 
size_t _bmsize( ___ segment seg, void __ based( void ) *memblock ); 
size_t _fmsize( void __ far *memblock ); 


size_t _nmsize( void __ near *memblock ); 


memblock Pointer to memory block 


seg Based-heap segment selector 


The _msize family of functions returns the size, in bytes, of the memory block 
allocated by a call to the appropriate version of the calloc, malloc, or realloc 
functions. 


In large data models (compact-, large-, and huge-model programs), _msize maps 
to _fmsize. In small data models (tiny-, small-, and medium-model programs), 
__msize maps to _nmsize. 


The _ nmsize function returns the size (in bytes) of the memory block allocated 
by a call to _nmalloc, and the _ fmsize function returns the size (in bytes) of the 
memory block allocated by a call to _fmalloc or _frealloc. The _bmsize function 
returns the size of a block allocated in segment seg by a call to _bmalloc, 
_bcalloc, or _ brealloc. 


The location of the memory block is indicated below: 


Function Data Segment 

_msize Depends on data model of program 

_bmsize Based heap segment specified by seg value 
_fmsize Far heap segment (outside default data segment) 
_nmsize Default data segment (inside near heap) 


All four functions return the size (in bytes) as an unsigned integer. 
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Compatibility 


See Also 


Example 


_msize 

Standards: None 

16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 


_bmsize, _ fmsize, _nmsize 


Standards: None 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: None 


calloc functions, _ expand functions, malloc functions, realloc functions 


/* REALLOC.C: This program allocates a block of memory for buffer 

* and then uses _msize to display the size of that block. Next, it 
* uses realloc to expand the amount of memory used by buffer 

* and then calls _msize again to display the new amount of 

* memory allocated to buffer. 


f#tinclude <stdio.h> 
d#Finclude <malloc.h> 
d#Finclude <stdlib.h> 


Output 


void main( void ) 


{ 
long *buffer; 
size_t size; 
if( (buffer = (long *)malloc( 1000 * sizeof( long ) )) == NULL ) 
exit( 1 ); 
size = _msize( buffer ); 
printf( "Size of block after malloc of 100@ longs: %u\n", size ); 
/* Reallocate and show new size: */ 
if( (buffer = realloc( buffer, size + (1000 * sizeof( long )) )) == NULL ) 
exit( 1 ); 
size = _msize( buffer ); 
printf( "Size of block after realloc of 100@ more longs: Zu\n", size ); 
free( buffer ); 
exit( @ ); 
} 


Size of block after malloc of 1000 longs: 4000 
Size of block after realloc of 100@ more longs: 8000 


Description 


Remarks 


Return Value 


Compatibility 
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_onexit, fonexit 


Register a routine to be called at exit time. 
#include <stdlib.h> 


_onexit_t _onexit( _onexit_t func ); 


_fonexit_t ___far _fonexit( _fonexit_t func ); 


func Pointer to function to be called at exit 


The _ onexit function is passed the address of a function (func) to be called when 
the program terminates normally. Successive calls to __onexit create a register of 
functions that is executed in LIFO (last-in—first-out) order. Except for DOS32X, 
no more than 32 functions can be registered with _ onexit; _ onexit returns the 
value NULL if the number of functions exceeds 32. For DOS32X, more than 32 
functions can be registered. Because the heap is used, the size of the function regis- 
ter is only limited by available memory in the heap. The functions passed to 
_onexit cannot take parameters. 


The _fonexit function is a far version of _ onexit; it can be used with any memory 
model. 


Neither _ onexit nor _ fonexit is part of the ANSI definition; instead, both are 
Microsoft extensions. The ANSI-standard atexit function does the same thing as 
_onexit and should be used instead of _ onexit when ANSI portability is desired. 


Both _onexit and _ fonexit return a pointer to the function if successful and return 
NULL if there is no space left to store the function pointer. 


_ onexit 

Standards: UNIX 

16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 


Use _ onexit for compatibility with ANSI naming conventions of non-ANSI func- 
tions. Use onexit and link with OLDNAMES.LIB for UNIX compatibility. 
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_ fonexit 


Standards: None 


16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: None 
See Also exit 


Example /* ONEXIT.C */ 
d#Finclude <stdlib.h> 
dEinclude <stdio.h> 


/* Prototypes */ 
void fnl( void ), fn2( void ), fn3( void ), fn4( void ); 


void main( void ) 
{ 

_onexit( fnl ); 

_onexit( fn2 ); 

_onexit( fn3 ); 

_onexit( fn4 ); 

printf( "This is executed first.\n" ); 
} 


void fnl() 
{ 

printf( "next.\n" ); 
} 


void fn2() 
{ 

printf( "executed " ); 
} 


void fn3() 
{ 

printf( “is ™ ); 
} 


void fn4() 
{ 

prince: “Eas. 
} 


Output This is executed first. 
This is executed next. 


Description 


Remarks 
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_open 
Opens a file. 
#include <fentl.h> 
#include <sys\types.h> 


#include <sys\stat.h> 


#include <io.h> 


int _open( char *filename, int oflag [[, int pmode]] ); 


filename Filename 
oflag Type of operations allowed 
pmode Permission mode 


The _ open function opens the file specified by filename and prepares the file for 
subsequent reading or writing, as defined by oflag. The oflag argument is an in- 
teger expression formed from one or more of the manifest constants defined in 
FCNTL.H (listed below). When two or more manifest constants are used to form 
the oflag argument, the constants are combined with the bitwise-OR operator (| ). 
See “File Handling” on page 21 for a discussion of binary and text modes. 


The FCNTL.H file defines the following manifest constants: 


Constant Meaning 

_O_APPEND Repositions the file pointer to the end of the file before every 
write operation. 

_O_ BINARY Opens file in binary (untranslated) mode. 

_O_CREAT Creates and opens a new file for writing; this has no effect if the 
file specified by filename exists. 

_O_EXCL Returns an error value if the file specified by filename exists. 
Only applies when used with _O_ CREAT. 

_O_RDONLY Opens file for reading only; if this flag is given, neither 
_O_RDWR nor _O_ WRONLY can be given. 

_O_RDWR Opens file for both reading and writing; if this flag is given, 


neither _O_RDONLY nor _O_ WRONLY can be given. 
_O_TEXT Opens file in text (translated) mode. 


034 


_open 


Constant Meaning 


_O_TRUNC Opens and truncates an existing file to zero length; the file must 
have write permission. The contents of the file are destroyed. If 
| this flag is given, you cannot specify _O_ RDONLY. 
_O_WRONLY Opens file for writing only; if this flag is given, neither 
—_O_RDONLY nor _O_ RDWR can be given. 


Warning! Use the O_TRUNC flag with care, as it destroys the complete con- 
tents of an existing file. 


Either _O_RDONLY, _O_RDWR, or _O_WRONLY must be given to specify 
the access mode. There is no default value for the access mode. 


The pmode argument is required only when __O_ CREAT is specified. If the file 
exists, pmode is ignored. Otherwise, pmode specifies the file’s permission settings, 
which are set when the new file is closed for the first time. The pmode is an in- 
teger expression containing one or both of the manifest constants _S_TWRITE 
and _S_ TREAD, defined in SYS\STAT.H. When both constants are given, they 
are joined with the bitwise-OR operator (| ). The meaning of the pmode argument 
is as follows: 


Value Meaning 

_S_IWRITE Writing permitted 
_S_IREAD Reading permitted 
_S_IREAD |_S_TWRITE Reading and writing permitted 


If write permission is not given, the file is read-only. With DOS, all files are read- 
able; it is not possible to give write-only permission. Thus the modes 
_S_ITWRITE and _S_ TREAD |_S_TWRITE are equivalent. 


The _ open function applies the current file-permission mask to pmode before set- 
ting the permissions (see _ umask). 


The filename argument used in the _open function is affected by the DOS 
APPEND command. 


Note that with DOS versions 3.0 and later, a problem occurs when SHARE is in- 
stalled and a new file is opened with oflag set to _O_ CREAT |_O_RDONLY 
or _O_CREAT |_O_ WRONLY and pmode set to _S_TREAD. Under these 
conditions, the operating system prematurely closes the file during system calls 
made within _ open. 


Return Value 
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To work around the problem, open the file with the pmode argument set to 
_S_IWRITE. Then close the file and use _chmod to change the access mode 
back to _S_TREAD. Another workaround is to open the file with pmode set to 
_S_ITREAD and oflag set to _O_ CREAT |_O_RDWR. 


The _ open function returns a file handle for the opened file. A return value of —1 
indicates an error, and errno is set to one of the following values: 


Value Meaning 
EACCES Given path name is a directory; or an attempt was made to open 
a read-only file for writing; or a sharing violation occurred (the 
file’s sharing mode does not allow the specified operations). 
EEXIST The _O_ CREAT and _O_EXCL flags are specified, but the 
named file already exists. 
EINVAL An invalid oflag or pmode argument was given. 
EMFILE No more file handles available (too many open files). 
ENOENT File or path name not found. 
Compatibility Standards: UNIX 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 
Use _open for compatibility with ANSI naming conventions of non-ANSI func- 
tions. Use open and link with OLDNAMES.LIB for UNIX compatibility. 
See Also _access, _chmod, _ close, _ creat, dup, _dup2, fopen, _sopen, _ umask 
Example /* OPEN.C: This program uses _open to open a file named OPEN.C for input 


* and a file named OPEN.OUT for output. The files are then closed. 


* / 


#Hinclude 
#Finclude 
dFinclude 
dFinclude 
d#Finclude 


<fcntl.h> 
<sys\types.h> 
<sys\stat.h> 
<i0.h> 
<stdio.h> 
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void main( void ) 


{ 
mnt. thi. Fiz: 
fhl = _open( "OPEN.C", _O_RDONLY ); 
FEC. FAL See) 
perror( “open failed on input file" ); 
else 
{ 
printf( "open succeeded on input file\n" ); 
_close( fhi ); 
} 
fh2 = _open( "OPEN.OUT", _O0 WRONLY | _O_CREAT, _S_IREAD | _S_IWRITE ); 
if( fh2 == -1 ) 
perror( “open failed on output file” ); 
else 
{ 
printf( "open succeeded on output file\n" ); 
_Close( fh2 ); 
} 
Output open succeeded on input file 


open succeeded on output file 


Description 


Remarks 


Return Value 


Compatibility 


See Also 
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_ outgtext 


Prints font-based text in graphics mode. 
#include <graph.h> 
void __ far _ outgtext( const char __ far *text ); 


text Text string to output 


The _ outgtext function outputs on the screen the null-terminated string that text 
points to. The text is output using the current font at the current graphics position 
and in the current color. 


No formatting is provided, in contrast to the standard console I/O library routines 
such as printf. 


After it outputs the text, _ outgtext updates the current graphics position. 


The _ outgtext function operates only in graphics video modes (e.g., 
_MRES4COLOR). Because it is a graphics function, the color of text is set by 
the _setcolor function, not by the _settextcolor function. Similarly, the position 
is affected by the _moveto function, not by the _ settextposition function. 


None. 


Standards: None 
16-Bit: DOS 
32-Bit: None 


_moveto functions, _setcolor, _setfont 
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Example /* OUTGTXT.C illustrates font output using functions: 


*k _registerfonts _setfont _outgtext 

* _unregisterfonts _getfontinfo _getgtextextent 
** _setgtextvector 

* / 


#Finclude <conio.h> 
#Hinclude <stdio.h> 
#Hinclude <stdlib.h> 
#Hinclude <string.h> 
#Hinclude <graph.h> 


d#Kdefine NFONTS 6 


unsigned char *face[NFONTS] = 


{ : 
"Courier", "Helvetica", "Times Roman", "Modern", "Script", "Roman" 
}3 
unsigned char *options[NFONTS] = 
{ 
"courier", "helv", "tms rmn", "modern", "script", “roman” 
es | | 


void main( void ) 

{ 
unsigned char list[20]; 
char fondir[_MAX_ PATH]; 
struct _videoconfig vc; 
struct _fontinfo fi; 
Short fontnum, x, y; 


/* Read header info from all .FON files in current or given directory. */ 
if( _registerfonts( "*.FON" ) <= @ ) 


! 
_outtext( "Enter full path where .FON files are located: " ); 
gets( fondir ); 
strcat( fondir, "\\*.FON" ); 
if( _registerfonts( fondir ) <= @ ) 
{ 
_outtext( "Error: can't register fonts" ); 
exit( 1 ); 
ii 
} 


/* Set highest available graphics mode and get configuration. */ 
if( ! setvideomode( _MAXRESMODE ) ) 

exit( 1 ); 
_getvideoconfig( &vc ); 


_ outgtext 539 


/* Display each font name centered on screen. */ 

for( fontnum = 0; fontnum < NFONTS; fontnum++ ) 

{ 
/* Build options string. */ 
Strcatt Streart strepyC 11st, "ts sop trons| Tontnum]) yy ps 
Streat( list, "h3@w24b" ); 


_clearscreen( _GCLEARSCREEN ); 
if( _setfont( list ) >= @ ) 
{ 
/* Use length of text and height of font to center text. */ 
xX = (vc.numxpixels / 2) - (_getgtextextent( face[fontnum] ) / 2); 
y = (vc.numypixels / 2) + (_getgtextextent( faceLfontnum] ) / 2); 
if( _getfontinfo( &fi ) ) 
{ 
_outtext( “Error: Can't get font information" ); 
break; 
} 
_moveto( x, y ); 
if( ve.numcolors > 2 ) 
_setcolor( fontnum + 2 ); 


/* Rotate and display text. */ 
_setgtextvector( 1, @ ); 
_outgtext( faceLfontnum] ); 
_setgtextvector( @, 1 ); 
_outgtext( faceLfontnum] ); 
_setgtextvector( -1, @ ); 
_outgtext( faceLfontnum] ); 
_setgtextvector( @, -1 ); 
_outgtext( face[lfontnum] ); 
} 
else 
ft 
_outtext( "Error: Can't set font: " ); 
_outtext( list ); 
} 
_getch(); 
} 
_unregisterfonts(); 
_setvideomode( _DEFAULTMODE ); 
exit( @ ); 
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_outmem 

Description Prints text of a specified length in graphics mode. 
#include <graph.h> 


void __ far _outmem( const char __ far *text, short length ); 


text Text string to output 
length Length of string to output 
Remarks The _outmem function outputs the string that text points to. The /ength argument 


specifies the number of characters to output. 


Unlike _ outtext, the _ outmem function prints all characters literally, including 
ASCII 10, 13, and 0 as the equivalent graphics characters. No formatting is pro- 
vided. Text is printed using the current text color, starting at the current text 
position. 


To output text using special fonts, you must use the _ outgtext function. 


Return Value None. 

Compatibility Standards: None 
16-Bit: DOS 
32-Bit: None 


See Also _outtext, _settextcolor, _settextposition, _settextwindow 
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Example /* QUTMEM.C illustrates: 
* _outmem 
x / 


dFinclude <stdio.h> 
#Hinclude <graph.h> 


void main( void ) 
f 
int i, len; 
char tmp[10]; 


_clearscreen( _GCLEARSCREEN ); 
for( i = 0; i < 256; i++ ) 


{ 
_settextposition( (i % 24) +1, (i / 24) * 7 ); 
len = sprintf( tmp, "%3d %c", i, i ); 
_outmem( tmp, len ); 

} 


_settextposition( 24, 1 ); 
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Description 


Remarks 


Return Value 


Compatibility 


See Also 


_outp, _outpw 


Outputs a byte (_ outp) or a word (_outpw) at a port. 
#include <conio.h> Required only for function declarations 


int _ outp( unsigned port, int databyte ); 


unsigned _ outpw( unsigned port, unsigned dataword ); 


port Port number 
databyte Output value 
dataword Output value 


The _outp and _ outpw functions write a byte and a word, respectively, to the 
specified output port. The port argument can be any unsigned integer in the range 
0 — 65,535; byte can be any integer in the range 0 — 255; and dataword can be any 
value in the range 0 — 65,535. 


The functions return the data output. There is no error return. 


Standards: None 
16-Bit: DOS 
32-Bit: None 


_inp, _inpw 
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Example 


/* QUTP.C: This program uses _inp and _outp to make sound of variable tone 
* and duration. 
a / 


dFinclude <conio.h> 
d#Finclude <stdio.h> 
dFAinclude <time.h> 


void Beep( unsigned duration, unsigned frequency ); /* Prototypes */ 
void Sleep( clock_t _wait ); 


void main ( main ) 
{ 
Beep( 698, 700 ); 
Beep( 523, 500 ); 
} 


/* Sounds the speaker for a time specified in microseconds by duration 
* at a pitch specified in hertz by frequency. 
« / 
void Beep( unsigned frequency, unsigned duration ) 
{ 
int control; 


/* If frequency is @, Beep doesn't try to make a sound. */ 
if( frequency ) 
{ 
/* 75 is about the shortest reliable duration of a sound. */ 
if( duration < 75 ) 
duration = 75; 


/* Prepare timer by sending 10111100 to port 43. */ 
_outp( @x43, @xb6 ); 


/* Divide input frequency by timer ticks per second and 
* write (byte by byte) to timer. 
* / 

frequency = (unsigned)(1193180L / frequency); 

_outp( @x42, (char)frequency ); 

_outp( @x42, (char)(frequency >> 8) ); 


/* Save speaker control byte. */ 
control = _inp( Qx61 ); 


/* Turn on the speaker (with bits @ and 1). */ 
_outp( @x61, control | @x3 ); 


044 
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Sleep( (clock_t)duration ); 


/* Turn speaker back on if necessary. */ 
if( frequency ) 
_outp( @x61, control ); 
} 


/* Pauses for a specified number of microseconds. 


void Sleep( clock_t _wait ) 
{ 
clock_t goal; 


goal = _wait + clock(); 
while( goal > clock() ) 


> 


* / 


Description 


Remarks 
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_ outtext 


Prints text in graphics mode. 
#include <graph.h> 
void __ far _ outtext( const char __ far *fext ); 


text Text string to output 


The _ outtext function outputs the null-terminated string that text points to. No for- 
matting is provided, in contrast to the standard console I/O library routines such as 
printf. This function will work in any screen mode. 


Text output begins at the current text position. 


To output text using special fonts, you must use the _ outgtext function. 


Return Value None. 

Compatibility Standards: None 
16-Bit: DOS 
32-Bit: None 


See Also 


Example 


_outmem, _ settextcolor, _ settextposition, _ settextwindow, _ wrapon 
\ 
/* QUTTXT.C: This example illustrates text output functions: 


** _gettextcolor _getbkcolor -_gettextposition -_outtext 
** _settextcolor _setbkcolor -_settextposition 
* / 


dFinclude <conio.h> 
dFinclude <stdio.h> 
#Hinclude <graph.h> 


char buffer [8@]; 
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void main( void ) 
{ 
/* Save original foreground, background, and text position */ 
short blink, fgd, oldfgd; 
long bgd, oldbgd; 
struct _rccoord oldpos; 


/* Save original foreground, background, and text position. */ 
oldfgd = _gettextcolor(); 

oldbgd _getbkcolor(); 

oldpos = _gettextposition(); 

_clearscreen( _GCLEARSCREEN ); 


/* First time no blink, second time blinking. */ 
for( blink = 0; blink <= 16; blink += 16 ) 


{ 
/* Loop through 8 background colors. */ 
for( bgd = @; bgd < 8; bgd++ ) 
{ 
_setbkcolor( bad ); 
_settextposition( (short)bgd + ((blink / 16) * 9) + 3, 1 ); 
_settextcolor( 7 ); 
sprintf(buffer, "Back: 4d Fore:", bgd ); 
_outtext( buffer ); 
/* Loop through 16 foreground colors. */ 
for( fgd = @; fgd < 16; fgdt++ ) 
{ 
_settextcolor( fgd + blink ); 
sprintf( buffer, " 42d ", fgd + blink ); 
_outtext( buffer ); 
} 
} 
} 
_getch(); 


/* Restore original foreground, background, and text position. */ 
_settextcolor( oldfgd ); 

_setbkcolor( oldbgd ); 

_clearscreen( _GCLEARSCREEN ); 

_settextposition( oldpos.row, oldpos.col ); 


Description 


Remarks 


Return Value 


Compatibility 


See Also 
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perror 


Prints an error message. 

#include <stdio.h> Required only for function declarations 
void perror( const char *string ); 

string String message to print 


The perror function prints an error message to stderr. The string argument is 
printed first, followed by a colon, then by the system error message for the last li- 
brary call that produced the error, and finally by a newline character. If string is a 
null pointer or a pointer to a null string, perror prints only the system error 
message. 


The actual error number is stored in the variable errno (defined in ERRNO.H). 
The system error messages are accessed through the variable sys_errlist, which is 
an array of messages ordered by error number. The perror function prints the ap- 
propriate error message by using the errno value as an index to sys_errlist. The 
value of the variable sys_nerr is defined as the maximum number of elements in 
the sys_errlist array. 


To produce accurate results, perror should be called immediately after a library 
routine returns with an error. Otherwise, the errno value may be overwritten by 
subsequent calls. 


Under DOS, some of the errno values listed in ERRNO.H are not used. These 
additional errno values are reserved for UNIX use. See “‘_doserrno, errno, 
sys_errlist, sys_nerr” on page 63 for a list of errno values used in DOS and the 
corresponding error messages. The perror function prints an empty string for any 
errno value not used under the operating system. 


None. 


Standards: ANSI, UNIX 
16-Bit: DOS, QWIN 
32-Bit: DOS32X 


clearerr, ferror, strerror 
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Example /* PERROR.C: This program attempts to open a file named NOSUCHF.ILE. 
* Since this file probably doesn't exist, an error message is displayed. 
* The same message is created using perror, strerror, and _strerror. 
a / 


d#Hinclude <fcntl.h> 
#Finclude <sys\types.h> 
d#Hinclude <sys\stat.h> 
#Hinclude <io.h> 
#Finclude <stdlib.h> 
#Hinclude <stdio.h> 
#Hinclude <string.h> 


void main( void ) 


{ 
int fh; 
if( (fh = _open( "NOSUCHF.ILE", _O RDONLY )) == -1 ) 
i: 
/* Three ways to create error message: */ 
perror( "“perror says open failed" ); 
printf( "strerror says open failed: %s\n", strerror( errno ) ); 
printf( _strerror( "_strerror says open failed" ) ); 
} 
else 
{ 
printf( "open succeeded on input file\n" ); 
_Close( fh ); 
} 
} 
Output perror says open failed: No such file or directory 


strerror says open failed: No such file or directory 
_strerror says open failed: No such file or directory 


Description 


Remarks 
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_ pg_analyzechart Functions 


Analyze a series of data. 
#include <pgchart.h> 


short __ far _pg_analyzechart( _chartenv __ far *env, 
char __ far * __ far *categories, float __far *values, short n ); 


short __ far _pg_analyzechartms( _chartenv __ far *env, 
char __ far * __ far “categories, float __ far *values, short nseries, short n, 
short arraydim, char __far * __far *serieslabels ); 


env Chart environment variable 
categories Array of category variables 
values Array of data values 

nseries Number of series to chart 

n Number of data values to chart 
arraydim Row dimension of data array 
serieslabels Array of labels for series 


The _ pg_analyzechart routines analyze a single or multiple series of data 
without actually displaying the presentation-graphic image. 


The _ pg_analyzechart function fills the chart environment with default values 
for a single-series bar, column, or line chart, depending on the type specified by 
the call to the _pg_defaultchart function. The variables calculated by 
_pg_analyzechart reflect the data given in the arguments categories and values. 
All arguments are the same as those used with the _ pg_ chart function. 


The _ pg_analyzechartms function fills the chart environment with default 
values for a multiseries bar, column, or line chart, depending on which type is 
specified in the _pg_defaultchart function. The variables calculated by 
_pg_analyzechartms reflect the data given in the arguments categories and 
values. All arguments are the same as those used with the _ pg_chartms function. 


Boolean flags in the chart environment, such as AUTOSCALE and LEGEND, 
should be set to TRUE before calling either __ pg_analyzechart function. This 
will ensure that the function will calculate all defaults. 
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Return Value 


Compatibility 


See Also 


Example 


For a discussion of the chart environment and related topics, see ““Presentation- 
Graphics Functions” on page 29. 


The _ pg_analyzechart and _ pg_ analyzechartms functions return 0 if there 
were no errors. A nonzero value indicates a failure. 


Standards: None 
16-Bit: DOS 
32-Bit: None 


_pg_chart functions, _ pg_defaultchart, _ pg _imitchart 


/* PGACHART.C: This example illustrates presentation-graphics 


analyze functions. 
The example uses 


_pg_analyzechartms 


The same principles apply for 


_pg_analyzepie _pg_analyzechart 
_pg_analyzescatter _pg_analyzescatterms 


#include <conio.h> 
#Hinclude <string.h> 
d#Finclude <stdlib.h> 
#Hinclude <graph.h> 
#Finclude <pgchart.h> 


dKdefine FALSE @ 
dtdefine TRUE 1 


/* Note data declared as a single-dimension array. The multiseries 
* Chart functions expect only one dimension. See _pg_chartms 
* example for alternate method using multidimension array. 


* / 


dKdefine TEAMS 4 
4tdefine MONTHS 3 
float __far valuesLTEAMS * MONTHS] = { .435, L522), 671, 


char 
char 


__far *months[MONTHS ] 
__far *teams[ TEAMS] = 


£5925 AST. .590, 

of 2S 624, .488, 

329, .226, 401 dees 
= { "May", "June", "July" }; 
{ "Reds", "Sox", "Cubs", "Mets" }; 
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void main( void ) 
{ 
_Chartenv env; 


/* Find a valid graphics mode. */ 
if( !_setvideomode( _MAXRESMODE ) ) 
exit( 1 ); 


_pg_initchart(); /* Initialize chart system. * / 
/* Default multiseries bar chart */ 

_pg_defaultchart( &env, _PG_BARCHART, _PG_PLAINBARS ); 

strcepy( env.maintitle.title, "Little League Records - Default" ); 
_pg_chartms( &env, months, values, TEAMS, MONTHS, MONTHS, teams ); 
_getch(); 

_clearscreen( _GCLEARSCREEN ); 


/* Analyze multiseries bar chart with autoscale. This sets all 
* default scale values. We want y axis values to be automatic. 
* / 
_pg_defaultchart( &env, _PG_BARCHART, _PG_PLAINBARS ); 
strcepy( env.maintitle.title, "Little League Records - Customized" ); 
env.xaxis.autoscale = TRUE; 
_pg_analyzechartms( &env, months, values, TEAMS, MONTHS, MONTHS, teams ); 


/* Now customize some of the x axis values. Then draw the chart. */ 
env.xaxis.autoscale = FALSE; 


env.xaxis.scalemax = 1.0; /* Make scale show @.@ to 1.0. * / 
env.xaxis.ticinterval = Q.2; /* Don't make scale too crowded. */ 
env.xaxis.ticdecimals = 3; /* Show three decimals. */ 


strcepy( env.xaxis.scaletitle.title, "Win/Loss Percentage” ); 
_pg_chartms( &env, months, values, TEAMS, MONTHS, MONTHS, teams ); 
_getch(); 


_setvideomode( _DEFAULTMODE ); 
exit( @ ); 


552 _pg_analyzepie 


_pg_analyzepie 


Description Analyzes a single series of data for a pie chart. 
#include <pgchart.h> 


short __ far _ pg_analyzepie( _chartenv __ far *env, 
char __ far * __ far “categories, float __far “values, 
short __ far *explode, short n ); 


env Chart environment variable 
categories Array of category variables 
values Array of data values 
explode Array of explode flags 
n Number of data values to chart 
Remarks The _pg_analyzepie function analyzes a single series of data without actually dis- 


playing the graphic image. 


The _ pg_analyzepie function fills the chart environment for a pie chart using the 
data contained in the array values. All arguments are the same as those used in the 
_pg_—chartpie function. : 


For a discussion of the chart environment and related topics, see “Presentation- 
Graphics Functions” on page 29. 


Return Value The _pg_analyzepie function returns 0 if there were no errors. A nonzero value 
indicates a failure. 


Compatibility Standards: None 
16-Bit: DOS 
32-Bit: None 
See Also _pg_chartpie, _ pg_defaultchart, _ pg_initchart 


Example See the example for _ pg_analyzechart. 


Description 


Remarks 
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_ pg_analyzescatter Functions 


Analyze a series of data for a scatter chart. 
#include <pgchart.h> 


short __ far _ pg_analyzescatter( _chartenv __ far *env, float __far *xvalues, 
float __ far *yvalues, short n ); 


short __ far _pg_analyzescatterms( _chartenv __ far *env, 
float __ far *xvalues, float __ far “yvalues, short nseries, short n, 
short rowdim, char __ far * __ far *serieslabels ); 


env Chart environment structure 
xvalues Array of x-axis data values 
yvalues Array of y-axis data values 

n Number of data values to chart 
nseries Number of series to chart 
rowdim Row dimension of data array 
serieslabels Array of labels for series 


The _pg_analyzescatter set of routines analyzes a single or multiple series of 
data without actually displaying the graphic image. 


The _ pg_analyzescatter function fills the chart environment for a single-series 
scatter diagram. The variables calculated by this function reflect the data given in 
the arguments xvalues and yvalues. All arguments are the same as those used in 
the _ pg_chartscatter function. 


The _ pg_analyzescatterms function fills the chart environment for a multiseries 
scatter diagram. The variables calculated by _ pg_analyzescatterms reflect the 
data given in the arguments xvalues and yvalues. All arguments are the same as 
those used in the function _ pg_chartscatterms. 


Boolean flags in the chart environment, such as AUTOSCALE and LEGEND, 
should be set to TRUE before calling _ pg_analyzescatterms; this ensures that 
the function will calculate all defaults. 


554 _pg_analyzescatter Functions 


Return Value 


Compatibility 


See Also 


Example 


For a discussion of the chart environment and related topics, see “Presentation- 
Graphics Functions” on page 29. 


The _pg_analyzescatter and _ pg_analyzescatterms functions return 0 if there 
were no errors. A nonzero value indicates a failure. 


Standards: None 
16-Bit: DOS 
32-Bit: None 


_.pg_chartscatter functions, _pg_defaultchart, _pg_initchart 


See the example for _ pg_ analyzechart. 


Description 


Remarks 
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_ pg_chart Functions 


Display single-series or multiseries charts. 
#include <pgchart.h> 


short __ far _pg_chart( _chartenv __ far *env, 
char __ far * __ far *categories, float __far *values, short n ); 


short __ far _pg_chartms( _chartenv __ far *env, 
char __far * __ far “categories, float __far *values, short nseries, short n, 
short arraydim, char __ far * __ far *serieslabels ); 


env Chart environment variable 
categories Array of category variables 
values Array of data values 

n Number of data values to chart 
nseries Number of series to chart 
arraydim Row dimension of data array 
serieslabels Array of labels for series 


The _ pg_chart function displays a single-series bar, column, or line chart, de- 
pending on the type specified in the chart environment variable (env). 


The _ pg_chartms function displays a multiseries bar, column, or line chart, de- 
pending on the type specified in the chart environment. All the series must contain 
the same number of data points, specified by the argument n. 


The array values is a two-dimensional array containing all value data for every ser- 
ies to be plotted on the chart. Each column of values represents a single series. The 
parameter rowdim 1s the integer value used to dimension rows in the array declara- 
tion for values. 


For example, the following code fragment declares the identifier values to bea 
two-dimensional floating-point array with 20 rows and 10 columns: 


#tdefine ARRAYDIM 20 
float values [LARRAYDIM][10]; 
short rowdim = ARRAYDIM; 
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Return Value 


Note that the number of columns in the values array cannot exceed 10, the maxi- 
mum number of data series on a single chart. Note also that rowdim must be 
greater than or equal to the argument n, and the column dimension in the array dec- 
laration must be greater than or equal to the argument nseries. If n and nseries are 
set to values less than the full dimensional size of the values array, only part of the 
data contained in values will be plotted. 


The array serieslabels holds the labels used in the chart legend to identify each 
series. 


For a discussion of the chart environment and related topics, see “Presentation- 
Graphics Functions” on page 29. 


The _pg_chart and _ pg_chartms functions return 0 if there were no errors. A 
nonzero value indicates a failure. 


Compatibility Standards: None 
16-Bit: DOS 
32-Bit: None 
See Also _pg_analyzechart functions, _ pg_defaultchart, _pg_initchart 


Example 


/* PGCHART.C: This example illustrates presentation-graphics support 
* routines and single-series chart routines, including 

* _pg_initchart  _pg_defaultchart  _pg_chart -_pg_chartpie 

* / 


#Hinclude <conio.h> 
#Hinclude <graph.h> 
##include <string.h> 
d#tinclude <stdlib.h> 
#include <pgchart.h> 


define COUNTRIES 5 

float __far value[COUNTRIES] = { 42.5, 1A3 35625 Clips, 32.6 }3 
char __far *category[COUNTRIES] = { "USSR", "France","USA", "UK", "Other™ 3+ 
short __far explode[COUNTRIES] = { @, im Q, 1, Q }; 


_pg_ chart Functions 


void main( void ) 
{ 
_chartenv env; 
short mode = _VRES16COLOR; 


/* Find a valid graphics mode. */ 
if( ! setvideomode( _MAXRESMODE ) ) 
OXTec 2 Js 


_pg_initchart(); /* Initialize chart system. */ 


/* Single-series bar chart */ 

_pg_defaultchart( &env, _PG_BARCHART, _PG_PLAINBARS ); 
strcpy( env.maintitle.title, "Widget Production” ); 
_pg_chart( &env, category, value, COUNTRIES ); 
_getch(); 

_clearscreen( _GCLEARSCREEN ); 


/* Single-series column chart */ 

_pg_defaultchart( &env, _PG_COLUMNCHART, _PG_PLAINBARS ); 
Sstrcepy( env.maintitle.title, "Widget Production" ); 
_pg_chart( &env, category, value, COUNTRIES ); 

_getch(); 

_clearscreen( _GCLEARSCREEN ); 


/* Pie chart */ 

_pg_defaultchart( &env, _PG_PIECHART, _PG_PERCENT ); 
strcpy( env.maintitle.title, "Widget Production" ); 
_pg_chartpie( &env, category, value, explode, COUNTRIES ); 
_getch(); 


_setvideomode( _DEFAULTMODE ); 
exit( @ ); 


J0/ 
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Description 


Remarks 


Return Value 


_ pg_chartpie 


Displays a pie chart. 
#include <pgchart.h> 


short __ far _pg_chartpie( _chartenv __ far “env, 
char __far * __ far *categories, float __far *values, short __far *explode, 
short n ); 


env Chart environment structure 
categories Array of category labels 
values Array of data values 

explode Array of explode flags 

n Number of data values to chart 


The _pg_chartpie function displays a pie chart for the data contained in the array 
values. Pie charts are formed from a single series of data—there is no multiseries 
version of pie charts as there is for other chart types. 


The array explode must be dimensioned so that its length is greater than or equal 
to the argument n. All entries in explode are either O or 1. If an entry is 1, the corre- 
sponding pie slice is displayed slightly removed from the rest of the pie. 


For example, if the explode array 1s initialized as 


short explode[5] = {@, 1, 0, 0, Q}; 


the pie slice corresponding to the second entry of the categories array will be 
displayed “exploded” from the other four slices. 


For a discussion of the chart environment and related topics, see “Presentation- 
Graphics Functions” on page 29. 


The _ pg_chartpie function returns 0 if there were no errors. A nonzero value 
indicates a failure. 


Compatibility 


See Also 


Example 


_pg_chartpie 


Standards: None 
16-Bit: DOS 
32-Bit: None 


_pg_analyzepie, _pg_defaultchart, _pg_initchart 


See the example for _ pg_ chart. 
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560  ###_pg_chartscatter Functions 


Description 


Remarks 


_pg_chartscatter Functions 


Display scatter charts. 
#include <pgchart.h> 


short __ far _pg_chartscatter( _chartenv __ far “env, float __far *xvalues, 
float __ far *yvalues, short n ); 


short __ far _ pg_chartscatterms( _chartenv __ far *env, float __ far *xvalues, 
float __ far *yvalues, short nseries, short n, short rowdim, 
char __ far * __ far *serieslabels ); 


env Chart environment structure 
xvalues Array of x-axis data values 
yvalues Array of y-axis data values 

n Number of data values to chart 
nseries Number of series to chart 
rowdim Row dimension of data array 
serieslabels Array of labels for series 


The _pg_chartscatter function displays a scatter diagram for a single series 
of data. 


The _ pg_chartscatterms function displays a scatter diagram for more than one 
series of data. 


The arguments xvalues and yvalues are two-dimensional arrays containing data for 
the x axis and y axis, respectively. Columns for each array hold data for individual 
series; thus the first columns of xvalues and yvalues contain plot data for the first 
series, the second columns contain plot data for the second series, and so forth. 


The n, rowdim, nseries, and serieslabels arguments fulfill the same purposes as 
those used in the _ pg_chartms function. See _ pg_chartms for an explanation of 
these arguments. 


For a discussion of the chart environment and related topics, see “Presentation- 
Graphics Functions” on page 29. 


Return Value 


Compatibility 


See Also 


Example 
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The _ pg_chartscatter and _ pg_chartscatterms functions return 0 if there were 
no errors. A nonzero value indicates a failure. 


Standards: None 
16-Bit: DOS 
32-Bit: None 


_pg_analyzescatter functions, _pg_defaultchart, _ pg_initchart 


See the example for _ pg_ chart. 


562 _pg_defaultchart 


Description 


Remarks 


_pg_defaultchart 


Initializes the chart environment. 
#include <pgchart.h> 


short __ far _pg_defaultchart( _chartenv __ far “env, short charttype, 


short chartstyle ); 
env Chart environment structure 
charttype Chart type 
chartstyle Chart style 


The _ pg_defaultchart function initializes all necessary variables in the chart en- 
vironment for the chart type by the variable charttype. 


All title fields in the environment structure are blanked. Titles should be set in the 
proper fields after calling _ pg_defaultchart. 


The charttype variable can be set to one of the following manifest constants: 


Chart Type Description 
_PG_BARCHART Bar chart 
—_PG_COLUMNCHART Column chart 
_PG_LINECHART Line chart 
_PG_PIECHART Pie chart 
_PG_SCATTERCHART Scatter chart 


The chartstyle variable specifies the style of the chart with either the number “1” 
or the number “2.” Each of the five types of presentation-graphics charts can ap- 
pear in two different chart styles, as described below: 


Chart Type Chart Style 1 Chart Style 2 
Bar Side by side Stacked 
Column Side by side Stacked 

Line Points with lines Points only 
Pie Percent No percent 


Scatter Points with lines Points only 


Return Value 


Compatibility 


See Also 


Example 
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In a pie chart, the pieces are “exploded” according to the explode array argument 
in the _ pg_chartpie function. In the “percent” format, percentages are printed 
next to each slice. Bar and column charts have only one style when displaying a 
single series of data. The styles “side by side” and “stacked” are applicable only 
when more than one series appears on the same chart. The first style arranges the 
bars or columns for the different series side by side, showing relative heights or 
lengths. The stacked style emphasizes relative sizes between bars and columns. 


The _pg_defaultchart function returns 0 if there were no errors. A nonzero value 
indicates a failure. 


Standards: None 
16-Bit: DOS 
32-Bit: None 


_pg_getchardef, _ pg_getpalette, _pg_getstyleset, _ pg hlabelchart, 
_pg_initchart, _pg_resetpalette, _pg_resetstyleset, _ pg_setchardef, 
_pg_setpalette, _pg_setstyleset, _ pg_vlabelchart 


See the example for _pg_ chart. 


564 _pg_getchardef 


Description 


Remarks 


Return Value 


Compatibility 


See Also 


_ pg_getchardef 


Gets the pixel bitmap for the specified character. 
#include <pgchart.h> 
short __ far _ pg_getchardef( short charnum, unsigned char __ far *chardef ); 


charnum ASCII number of character 


chardef Pointer to 8-by-8 bitmap array 


The _pg_ getchardef function retrieves the current 8-by-8 pixel bitmap for the 
character having the ASCII number charnum. The bitmap is stored in the chardef 
array. 


The _ pg_ getchardef function returns 0 if there were no errors. A nonzero value 
indicates an error. 


Standards: None 
16-Bit: DOS 
32-Bit: None 


_pg_defaultchart, _ pg_initchart, _ pg_setchardef 


Description 


Remarks 


Return Value 


Compatibility 


See Also 


Example 
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_pg_getpalette 


Gets palette colors, line styles, and patterns. 
#include <pgchart.h> 
short __ far _ pg_ getpalette( _paletteentry __ far *palette ); 


palette Pointer to first palette structure in array 


The _ pg_ getpalette function retrieves palette colors, line styles, fill patterns, and 
plot characters for all palettes. The pointer palette points to an array of palette 
structures that will contain the desired palette values. 


The palette used by the presentation-graphics routines is independent of the palette 
used by the low-level graphics routines. 


The function _pg_ getpalette returns 0 if there were no errors, and it returns the 
value _BADSCREENMODE if current palettes have not been initialized by a 
previous call to_pg_setpalette. 


Standards: None 
16-Bit: DOS 
32-Bit: None 


_pg_defaultchart, _pg_initchart, _ pg_resetpalette, _pg_setpalette 


/* PGGPAL.C: This example illustrates presentation-graphics palettes 


* and the routines that modify them, including 


*K 


* / 


_pg_getpalette _pg_resetpalette _pg_setstyleset 
_pg_getstyleset _pg_resetstyleset _pg_vlabelchart 
_pg_hlabelchart _pg_setpalette 


#Hinclude <conio.h> 
dHinclude <string.h> 
#Hinclude <stdlib.h> 
#Hinclude <graph.h> 
#Hinclude <pgchart.h> 


_pg_ getpalette 


d#define TEAMS 2 
dKdefine MONTHS 3 
float __far values[TEAMS][MONTHS] = 


char __far *months[ MONTHS ] 
char __far *teams[ TEAMS] = 


{ "Cubs" ; 


Ga. eg 
t. 35335 


{ "May" 


"Rads" }3 


ol ag ae .671 3 
431, 401 3} 3; 
‘ "June", "July" } 


_fillmap filll = { @x99, @x33, Qx66, @xcc, 0x99, 0x33, @x66, Q@xcc }; 
_fillmap fill2 = { @x99, @xcc, 0x66, @x33, Q@x99, @xcc, 9x66, @x33 }; 


_styleset styles; 
_palettetype pal; 


void main( void ) 
{. 
_chartenv env; 
Short mode = _VRESI16COLOR; 


/* Find a valid graphics mode. */ 


if( !_setvideomode( _MAXRESMODE ) ) 


exit( 1 ); 


_pg_initchart(); 


/* 


Initialize chart system. 


/* Modify global set of line styles used for borders, grids, and 
* data connectors. Note that this change is used before 
* pg defaultchart, which will use the style set. 


* / 
_pg_getstyleset( styles ); 
styles[1] = @x5555; 
_pg_setstyleset( styles ); 


/* 
/* 
/* 


Get styles and modify 
style 1 (used for 
borders)—then set new. 


_pg_defaultchart( &env, _~PG_BARCHART, _PG_PLAINBARS ); 


/* Modify palette for data lines, colors, fill patterns, and 
* characters. Note that the line styles are set in the palette, not 
* jin the style set, so that only data connectors will be affected. 


* / 
_pg_getpalette( pal ); 
pal{l].plotchar = 16; 
pal[2].plotchar = 1/7; 
memcpy( pal[l].fill, filll, 8 ); 
memcpy( pal[2].fill, fill2, 8 ); 
palf{lj.color = 3; 

pal{2].color = 4; 

palLl].style = @xfcfc; 
pall2].style = 0x0303; 
_pg_setpalette( pal ); 


/* 
/* 


/* 


/* 


/* 


/* 


Get default palette. 
Set to ASCII 16 and 17. 


Copy fill masks to palette. 


Change palette colors. 


Change palette line styles. 


Put modified palette. 


* / 


* / 
* / 
* / 


* / 
* / 


* / 


* / 


* / 


* / 
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/* Multiseries bar chart */ 
strcpy( env.maintitle.title, "Little League Records - Customized" ); 
_pg_chartms( &env, months, (float __far *)values, 
TEAMS, MONTHS, MONTHS, teams ); 
_getch(); 
_clearscreen( _GCLEARSCREEN ); 


/* Multiseries line chart */ 
_pg_defaultchart( &env, _PG_LINECHART, _PG_POINTANDLINE ); 
strcpy( env.maintitle.title, "Little League Records - Customized" ); 
_pg_chartms( &env, months, (float __far *)values, 
TEAMS, MONTHS, MONTHS, teams ); 


/* Print labels. */ 


_pg_hlabelchart( &env, (short)(Cenv.chartwindow.x2 * .75), 
(short)(env.chartwindow.y2 * .1@), 
12, "Up and up!" ); 
_pg_vlabelchart( &env, (short)(Cenv.chartwindow.x2 * .75), 
(short) (env.chartwindow.y2 * .45), 
13, "Sliding down!" ); 
_getch(); 
_clearscreen( _GCLEARSCREEN ); 
_pg_resetpalette(); /* Restore default palette * / 
_pg_resetstyleset(); /* and style set. * / 


/* Multiseries bar chart */ 
_pg_defaultchart( &env, _PG_BARCHART, _PG_PLAINBARS ); 
strcpy( env.maintitle.title, "Little League Records - Default" ); 
_pg_chartms( &env, months, (float __far *)values, 
TEAMS, MONTHS, MONTHS, teams ); 
_getch(); 
_clearscreen( _GCLEARSCREEN ); 


/* Multiseries line chart */ 
_pg_defaultchart( &env, _PG_LINECHART, _PG_POINTANDLINE ); 
strcpy( env.maintitle.title, "Little League Records - Default" ); 
_pg_chartms( &env, months, (float __far *)values, 

TEAMS, MONTHS, MONTHS, teams ); 
_getch(); 


_setvideomode( _DEFAULTMODE ); 
exit( @ ); 


568 _ pg_getstyleset 
_ pg_getstyleset 

Description Gets the contents of the current styleset array. 
#include <pgchart.h> 


void __ far _pg_getstyleset( unsigned short __ far *styleset ); 


styleset Pointer to current styleset array 
Remarks The _ pg_ getstyleset function retrieves the contents of the current styleset array. 
Return Value None. 
Compatibility Standards: None 
16-Bit: DOS 
32-Bit: None 
See Also _pg_defaultchart, _ pg_initchart, _pg_resetstyleset, _pg_setstyleset 


Example See the example for _ pg_ getpalette. 


Description 


Remarks 


Return Value 


Compatibility 


See Also 


Example 
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_pg_hlabelchart 


Writes text horizontaily on the screen. 
#include <pgchart.h> 


short __ far _ pg_hlabelchart( _chartenv __ far *env, short x, short y, 
short color, char __ far *label ); 


env Chart environment structure 
x x-coordinate for text 

y Pixel y-coordinate for text 
color Color code for text 

label Label text 


The _ pg_hlabelchart function writes text horizontally on the screen. The argu- 
ments x and y are pixel coordinates for the beginning location of text relative to 
the upper-left corner of the chart window. 


The _ pg_hlabelchart functions return 0 if there were no errors. A nonzero value 
indicates a failure. 


Standards: None 
16-Bit: DOS 
32-Bit: None 


_pg_defaultchart, _pg_initchart, _ pg_vlabelchart 


See the example for __pg_ getpalette. 


570 _pg_initchart 


Description 


Remarks 


Return Value 


Compatibility 


See Also 


Example 


_ pg_initchart 


Initializes presentation graphics. 
#include <pgchart.h> 


short __ far _ pg_initchart( void ); 


The _ pg_initchart function initializes the presentation-graphics package. It 
initializes the color and style pools, resets the chartline styleset, builds default 
palette modes, and reads the presentation-graphics font definition from the disk. 
This function is required in all programs that use presentation graphics. The 
_pg_initchart function must be called before any of the other functions in the 
presentation-graphics library. 


The _ pg_initchart function assumes a valid graphics mode has been established. 
Therefore, it must be called only after a successful call to the library function 
_setvideomode. 


Note The _ pg_initchart function can only be called after using the 
_setvideomode function to establish the video mode. Also, _ pg_initchart must 
be called after each change of the video mode. | 


The _ pg_initchart functions return 0 if there were no errors. A nonzero value in- 
dicates a failure. 


Standards: None 

16-Bit: DOS 

32-Bit: None 

_pg_—defaultchart, _pg_getchardef, _pg_getpalette, _ pg_getstyleset, 
_pg_—hlabelchart, _ pg_resetpalette, _resetstyleset, _ pg_setchardef, 
_pg_setpalette, _pg_setstyleset, _pg_vlabelchart, _setvideomode 


See the example for _ pg_ chart. 


Description 


Remarks 


Return Value 


Compatibility 


See Also 


Example 
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_pg_resetpalette 


Resets palette colors, line styles, and patterns to default values. 
#include <pgchart.h> 


short __ far _ pg_resetpalette( void ); 


The _ pg_resetpalette function sets the palette colors, line styles, fill patterns, and 
plot characters for the palette to the default for the current screen mode. 


The palette used by the presentation-graphics routines 1s independent of the palette 
used by the low-level graphics routines. 


The _ pg_ resetpalette function returns 0 if there were no errors. If the screen 
mode is not valid, the value _BADSCREENMODE is returned. 


Standards: None 
16-Bit: DOS 
32-Bit: None 


_pg_defaultchart, _ pg_getpalette, _pg_initchart, _pg_setpalette 


See the example for _ pg_ getpalette. 


572  _pg_resetstyleset 


Description 


Remarks 


Return Value 


Compatibility 


See Also 


Example 


_ pg_resetstyleset 


Resets styleset to default values. 
#include <pgchart.h> 


void __ far _pg_resetstyleset( void ); 

The _ pg_resetstyleset function reinitializes the styleset to the default values for 
the current screen mode. 

None. 


Standards: None 
16-Bit: DOS 
32-Bit: None 


_pg_defaultchart, _ pg_getstyleset, _pg_imitchart, _ pg_setstyleset 


See the example for _ pg_ getpalette. 
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_ pg_setchardef 
Description Sets the pixel bit map for the specified character. 
#include <pgchart.h> 


short __ far _pg_setchardef( short charnum, unsigned char __ far *chardef ); 


charnum ASCII number of character 
chardef Pointer to an 8-by-8 bitmap array for the character 
Remarks The _ pg_setchardef function sets the 8-by-8 pixel bitmap for the character with 


the ASCII number charnum. The bitmap is stored in the chardef array. 


Return Value The _ pg_setchardef function returns 0 if there was no error. A nonzero value in- 
dicates an error. 


Compatibility Standards: None 
16-Bit: DOS 
32-Bit: None 


See Also _pg_defaultchart, _pg_getchardef, _ pg_initchart 


574  _pg_setpalette 


Description 


Remarks 


Return Value 


Compatibility 


See Also 


Example 


_ pg_setpalette 


Sets palette colors, line styles, and patterns. 
#include <pgchart.h> 
short __far _pg_setpalette( _paletteentry __ far *palette ); 


palette Pointer to first palette structure in array 


The _ pg_setpalette function sets palette colors, line styles, fill patterns, and plot 
characters for all palettes. The pointer palette points to an array of palette struc- 
tures that contain the desired palette values. 


The palette used by the presentation-graphics routines is independent of the palette 
used by the low-level graphics routines. 


The _ pg_setpalette function returns 0 if there were no errors. If the new palettes 
are not valid, the value_BADSCREENMODE is returned. 


Standards: None 
16-Bit: DOS 
32-Bit: None 


_pg_defaultchart, _ pg_getpalette, _pg_initchart, _ pg_resetpalette 


See the example for _ pg_ getpalette. 
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_pg_setstyleset 


Description Sets the current styleset. 


#include <pgchart.h> 


void __ far _pg_setstyleset( unsigned short __ far *styleset ); 


styleset Pointer to new styleset 
Remarks The _ pg_setstyleset function sets the current styleset. 
Return Value None. 
Compatibility Standards: None 
16-Bit: DOS 
32-Bit: None 
See Also _pg_defaultchart, _pg_getstyleset, _pg_initchart, _ pg_resetstyleset 


Example See the example for _ pg_ getpalette. 
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Description 


Remarks 


Return Value 


Compatibility 


See Also 


Example 


_ pg_viabelchart 


Writes text vertically on the screen. 
#include <pgchart.h> 


short __ far _ pg_vlabelchart( _chartenv __ far *env, short x, short y, 
short color, char __ far *label ); 


env Chart environment structure 
x Pixel x coordinate for text 

y Pixel y coordinate for text 
color Color code for text 

label Label text 


The _ pg_vlabelchart function writes text vertically on the screen. The arguments 
x and y are pixel coordinates for the beginning location of text relative to the upper- 
left corner of the chart window. 


The _ pg_vlabelchart function returns 0 if there were no errors. A nonzero value 
indicates a failure. 


Standards: None 
16-Bit: DOS 
32-Bit: None 


_pg_defaultchart, _ pg_hlabelchart, _pg_initchart 


See the example for _ pg_ getpalette. 


Description 


Remarks 
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_ pie Functions 


Draw wedge-shaped figures. 
#include <graph.h> 


short __ far _ pie( short control, short x/, short y/, short x2, short y2, short x3, 
short y3, short x4, short y4 ); 


short __ far _ pie_w( short control, double x/, double y/, double x2, double y2, 
double x3, double y3, double x4, double y4 ); 


short __ far _ pie_ wxy( short control, struct _wxycoord __ far *pwxy1/, 
struct _ wxycoord __ far *pwxy2, struct _ wxycoord __far *pwxy3, 
struct _ wxycoord __ far*pwxy4 ); 


control Fill-control constant 

xl, yl Upper-left corner of bounding rectangle 

x2, y2 Lower-right corner of bounding rectangle 

x3, y3 Second point of start vector (center of bounding 
rectangle is first point) 

x4, y4 Second point of end vector (center of bounding 
rectangle is first point) 

pwxyl Upper-left corner of bounding rectangle 

pwxy2 Lower-right corner of bounding rectangle 

pwxy3 Second point of start vector (center of bounding 


rectangle is first point) 


pwxy4 Second point of end vector (center of bounding 
rectangle is first point) 


The _ pie functions draw a pie-shaped wedge by drawing an elliptical arc whose 
center and two endpoints are joined by lines. 


The center of the pie is the center of the bounding rectangle, which is defined by 
points (x/, y/) and (x2, y2) for _ pie and _ pie_w and by points pwxy/ and pwxy2 
for _plie_wxy. The pie starts where it intersects an imaginary line extending from 
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the center of the arc through (x3, y3) for _ pie and _ pie_ w and through pwxy3 for 

_pie_wxy. It is drawn counterclockwise about the center of the arc, ending where 
it intersects an imaginary line extending from the center of the arc through (x4, y4) 
for _pie and _ pie_w and through pwxy4 for _ pie_ wxy. 


The _ pie routine uses the view coordinate system. The _ pie_ w and _ pie_ wxy 
functions use the real-valued window coordinate system. The arc is drawn using 
the current color. Since an arc does not define a closed area, it is not filled. 


The _wxycoord structure is defined in GRAPH.H and contains the following 


elements: 

Element Description 

double wx Window x coordinate 
double wy Window y coordinate 


The wedge is drawn using the current color moving in a counterclockwise direc- 
tion. The control parameter can be one of the following manifest constants: 


Constant Action 
_GFILLINTERIOR Fills the figure using the current color and fill mask 
_GBORDER Does not fill the figure 


The control option given by _GFILLINTERIOR is equivalent to a subsequent 
call to the _ floodfill function using the approximate center of the pie as the 
Starting point and the current color (set by _ setcolor) as the boundary color. Use 
the _ getarcinfo function to find the exact starting point. 


Return Value These functions return a nonzero value if successful; otherwise, they return 0. 
Compatibility Standards: None 

16-Bit: DOS 

32-Bit: None 
See Also _are functions, _ ellipse functions, _floodfill, _ getarcinfo, _getcolor, _lineto 


functions, _rectangle functions, _setcolor, _setfillmask 
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Example /* PIE.C: This program draws a pie-shaped figure. */ 


deinclude <stdlib.h> 
dAinclude <conio.h> 
#Hinclude <graph.h> 


void main( void ) 


{ 
/* Find a valid graphics mode. */ 


if( !_setvideomode( _MAXRESMODE ) ) 
PREG -)5 


_pie( _GBORDER, 80, 50, 240, 150, 240, 12, @, 150 ); 
_getch(); 


_setvideomode( _DEFAULTMODE ); 
exit( @ ); 
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_ polygon Functions 


Description Draw polygon shapes. 
#include <graph.h> 


short __far _ polygon( short control, const struct _xycoord __ far *noints, 
short numpoints ); 


short __ far _ polygon_ w( short control, const double __far *points, 
short numpoints ); 


short __ far _ polygon_ wxy( short control, 
const struct _ wxycoord __ far *points, short numpoints ); 


control Fill flag 
points Pointer to an array of structures or doubles defin- 
ing the polygon 
numpoints Number of points 
Remarks The _ polygon functions draw polygons. The border of the polygon is drawn in 


the current color and line style. The _ polygon routine uses the view coordinate 
system (expressed in _xycoord structures), and the _ polygon_ wxy and 

_ polygon_w routines use real-valued window coordinates (expressed in 
_wxycoord structures and in pairs of double-precision floating-point values, 
respectively). 


The argument points is an array of _xycoord or _ wxycoord structures or pairs of 
doubles, each of which specifies one of the polygon’s vertices. (For _ polygon_w, 
points[{O] and points[1] specify the x and y coordinates, respectively, of the first 
point.) If the first point does not equal the last point, the _ polygon functions use 
them to provide a closing edge. 


The argument numpoints indicates the number of elements (the number of ver- 
tices) in the points array. The minimum number of points is 3, the maximum is 
16,381. | 


a OI ct 
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The control argument can be one of the following manifest constants: 


Constant 


_GFILLINTERIOR 


_GBORDER 


Action 


Fills the polygon with the current fill mask using a scan 
fill 
Does not fill the polygon 


The _setwritemode, _ setlinestyle, and _setfillmask functions all affect the out- 
put from the_ polygon functions. 


If you try to fill the polgon with the _ floodfill function, the polygon must be 
bordered by a solid line-style pattern. 


Return Value The _ polygon functions return a nonzero value if the arc is successfully drawn; 
otherwise, they return 0. 

Compatibility Standards: None 
16-Bit: DOS 
32-Bit: None 

See Also _ ellipse functions, _ floodfill, _lineto functions, _ pie functions, _rectangle 
functions, _setcolor, _setfillmask, _setlinestyle, _setwritemode 

Example /* POLYGON.C: This program draws a star-shaped polygon. */ 


#include 
#tinclude 
dFinclude 
#Finclude 
#include 


<conio.h> 
<stdlib.h> 
<graph.h> 
<math.h> 
<stdlib.h> 


dEKdefine PI 3.1415 


void main( void ) 

{ 
short side, radius = 
double radians; 
struct _xycoord polyside[5]; 
struct _videoconfig vc; 


/* Find a valid graphics mode. */ 
1A 
exit 2s 


_getvideoconfig( &vc ); 


_setvieworg( vc.numxpixels / 2, vc. 


! setvideomode( _MAXRESMODE ) ) 


numypixels / 2 ); 
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/* Calculate points of star every 144 degrees, then connect them. */ 
for( side = 0; side < 5; sidet+ ) 


{ 
radians = 144 * PI / 180; 
polyside[side].xcoord = x + (short)(cos( side * radians ) * radius); 
polyside[side].ycoord = y + (short)(sin( side * radians ) * radius); 
} 
_polygon( _GFILLINTERIOR, polyside, 5 ); 
_getch(); 
_setvideomode( _DEFAULTMODE ); 
exit( @ ); 


Description 


Remarks 


Return Value 


Compatibility 
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pow Functions 


Calculate x raised to the power of y. 
#include <math.h> 


double pow( double x, double y ); 
long double _ powl( long double x, long double y ); 


x Number to be raised 


Power of x 


The pow and _ powl functions compute x raised to the power of y. 


The _ powl function is the 80-bit counterpart, and it uses an 80-bit, 10-byte co- 
processor form of arguments and return values. See the reference page on the long 
double functions for more details on this data type. 


The pow and _ powl functions return the value of x”. If x is not 0.0 and y is 0.0, 
pow and _ powl return the value 1. If x is 0.0 and y is negative, pow and _ powl set 
errno to EDOM and return 0.0. If both x and y are 0.0, or if x is negative and y is 
not an integer, the function prints a_ DOMAIN error message to stderr, sets 
errno to EDOM, and returns 0.0. If an overflow results, the function sets errno to 
ERANGE and returns + HUGE_ VAL. No message is printed on overflow or 
underflow. 


The pow function does not recognize integral floating-point values greater than 
20% such as 1.0E10Q. 


pow 
Standards: ANSI, UNIX 
16-Bit: DOS, QWIN, WIN, WIN DLL 


32-Bit: DOS32X 
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_ powl 


Standards: None 


16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: None 
See Also exp, log functions, sqrt - 


Example /* POW.C */ 
d#Hinclude <math.h> 
d#Hinclude <stdio.h> 


void main( void ) 


{ 

double x = 2.0, y = 3.0, Z; 

Z = pow( x, y ); 

printf( "%.1f to the power of %.1f is %.1f\n", x, y, z ); 
} 


Output 2.8 to the power of 3.0 is 8.0 


Description 


Remarks 
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printf 


Prints formatted output to the standard output stream. 
#include <stdio.h> 
int printf( const char *format ||, argument]... )s 


format Format control 


argument Optional arguments 


The printf function formats and prints a series of characters and values to the 
standard output stream, stdout. The format argument consists of ordinary charac- 
ters, escape sequences, and (if arguments follow format) format specifications. 
The ordinary characters and escape sequences are copied to stdout in order of 
their appearance. For example, the line 


printf("Line one\n\t\tLine two\n"); 


produces the output 


Line one 
Line two 


If arguments follow the format string, the format string must contain specifications 
that determine the output format for the arguments. 


Format specifications always begin with a percent sign (%) and are read left to 
right. When the first format specification (if any) is encountered, the value of the 
first argument after format is converted and output accordingly. The second for- 
mat specification causes the second argument to be converted and output, and so 
on. If there are more arguments than there are format specifications, the extra argu- 
ments are ignored. The results are undefined if there are not enough arguments for 
all the format specifications. 


Format Specification Fields 


A format specification, which consists of optional and required fields, has the 
following form: 


% |[flags]| [width] [.precision]] [{F | Nl hl11L}]type 
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Each field of the format specification is a single character or a number signifying a 
particular format option. The simplest format specification contains only the per- 
cent sign and a type character (for example, %s). The optional fields, which appear 
before the type character, control other aspects of the formatting. The fields in a 
printf format specification are described in the following list: 


Field Description 


type Required character that determines whether the associated argument 
is interpreted as a character, a string, or a number. (See Table R.2.) 


flags Optional character or characters that control justification of output 
and printing of signs, blanks, decimal points, and octal and 
hexadecimal prefixes. (See Table R.3.) More than one flag can appear 
in a format specification. 


width Optional number that specifies minimum number of characters 
output. 
precision Optional number that specifies maximum number of characters 


printed for all or part of the output field, or mintmum number of 
digits printed for integer values. (See Table R.4.) 


F, N Optional prefixes that refer to the “distance” to the object being 
printed (near or far). 


F and N are not part of the ANSI definition for printf. They are 
Microsoft extensions that should not be used if ANSI portability is 
desired. 


h, 1, L Optional prefixes that determine the size of the argument expected, 
as shown below: 


Prefix Use 


h Used with the integer types d, i, 0, x, and X to specify 
that the argument is short int, or with u to specify short 
unsigned int. [f used with %p, it indicates a 16-bit 
pointer. 

| Used with d, i, 0, x, and X types to specify that the 
argument is long int, or with u to specify long unsigned 
int; also used with e, E, f, g, and G types to specify 
double rather than float. If used with %p, it indicates a 
32-bit pointer. 

L Used with e, E, f, g, and G types to specify long double. 


If a percent sign is followed by a character that has no meaning as a format field, 
the character is copied to stdout. For example, to print a percent-sign character, 
use %%. 
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Type Field Characters 

The type character is the only required format field for the printf function; it ap- 
pears after any optional format fields. The type character determines whether the 
associated argument is interpreted as a character, string, or number (see Table R.2). 


Table R.2. Type Characters for printf 


Character Type Output Format 

d int Signed decimal integer. 

i int Signed decimal integer. 

u int Unsigned decimal integer. 

0 int Unsigned octal integer. 

xX int Unsigned hexadecimal integer, using “abcdef.” 

4 int Unsigned hexadecimal integer, using “ABCDEF.” 

f double Signed value having the form [—|dddd.dddd, where dddd 


is one or more decimal digits. The number of digits be- 
fore the decimal point depends on the magnitude of the 
number, and the number of digits after the decimal point 
depends on the requested precision. 


e double Signed value having the form [—]d.dddd e [sign]ddd, 
where d is a single decimal digit, dddd is one or more 
decimal digits, ddd is exactly three decimal digits, and 
sign 1s + Or -. 

E double Identical to the e format, except that E, rather than e, 
introduces the exponent. 


g double Signed value printed in f or e format, whichever is more 
compact for the given value and precision. The e format 
is used only when the exponent of the value is less than 
—4 or greater than or equal to the precision argument. 
Trailing zeros are truncated, and the decimal point 
appears only if one or more digits follow it. 


G double Identical to the g format, except that G, rather than g, 
introduces the exponent (where appropriate). 
c int Single character. 
S String Characters printed up to the first null character (’\0’) or 
until the precision value is reached. 
n Pointer to Number of characters successfully written so far to the 
integer stream or buffer; this value 1s stored in the integer whose 
address is given as the argument. 
p Far pointer Prints the address pointed to by the argument in the form 
to void xxxx:yyyy, where xxxx is the segment and yyyy is the 


offset, and the digits x and y are uppercase hexadecimal 
digits; %hp indicates a near pointer and prints only the 
offset of the address. 
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Flag Directives 
The first optional field of the format specification is flag. A flag directive is a char- 
acter that justifies output and prints signs, blanks, decimal points, and octal and 


hexadecimal prefixes. More than one flag directive may appear in a format specifi- 
cation. (See Table R.3.) 


Table R.3. Flag Characters for printf 


Flag 


blank (°’) 


Meaning 


Left justify the result within the given 
field width. 


Prefix the output value with a sign 

(+ or —) if the output value is of a signed 
type. 

If width is prefixed with 0, zeros are 
added until the minimum width is 
reached. If O and — appear, the 0 is 
ignored. If 0 is specified with an integer 
format (i, u, x, X, 0, d), the O is ignored. 
Prefix the output value with a blank if the 
output value is signed and positive; the 
blank is ignored if both the blank and + 
flags appear. 


When used with the o, x, or X format, the 
# flag prefixes any nonzero output value 
with 0, Ox, or OX, respectively. 

When used with the e, E, or f format, the 
# flag forces the output value to contain a 
decimal point in all cases. 

When used with the g or G format, the # 
flag forces the output value to contain a 
decimal point in all cases and prevents 
the truncation of trailing zeros. 


Ignored when used with ¢, d, i, u, ors. 


Width Specification 


The second optional field of the format specification is the width specification. 
The width argument is a nonnegative decimal integer controlling the minimum 
number of characters printed. If the number of characters in the output value is 
less than the specified width, blanks are added to the left or the right of the 
values—depending on whether the — flag (for left justification) is specified—until 
the minimum width is reached. If width is prefixed with 0, zeros are added until 
the minimum width is reached (not useful for left-justified numbers). 


Default 
Right justify. 


Sign appears only for 
negative signed values (—). 


No padding. 


No blank appears. 


No blank appears. 


Decimal point appears 
only if digits follow it. 


Decimal point appears 
only if digits follow it. 
Trailing zeros are 
truncated. 
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The width specification never causes a value to be truncated. If the number of char- 
acters in the output value is greater than the specified width, or width is not given, 
all characters of the value are printed (subject to the precision specification). 


The width specification may be an asterisk (*), in which case an int argument 
from the argument list supplies the value. The width argument must precede the 
value being formatted in the argument list. A nonexistent or small field width does 
not cause a truncation of a field; if the result of a conversion 1s wider than the field 
width, the field expands to contain the conversion result. 


Precision Specification 

The third optional field of the format specification is the precision specification. It 
specifies a nonnegative decimal integer, preceded by a period (.), which specifies 
the number of characters to be printed, the number of decimal places, or the num- 
ber of significant digits. (See Table R.4.) Unlike the width specification, the preci- 
sion specification can cause truncation of the output value, or rounding in the case 
of a floating-point value. If precision is specified as zero and the value to be con- 
verted is zero, the result is no characters output, as shown below: 


printf( "%.@d", @ ); /* No characters output */ 


The precision specification may be an asterisk (+), in which case an int argument 
from the argument list supplies the value. The precision argument must precede 
the value being formatted in the argument list. 


The interpretation of the precision value and the default when precision is omitted 
depend on the type, as shown in Table R.4. 


Table R.4 How printf Precision Values Affect Type 


Type Meaning Default 

d The precision specifies the minimum Default precision is |. 

i number of digits to be printed. If the 

U number of digits in the argument ts less 

0 than precision, the output value is padded 

x on the left with zeros. The value is not 

X truncated when the number of digits 
exceeds precision. 

e The precision specifies the number of Default precision is 6; if 

E digits to be printed after the decimal precision is O or the period (.) 
point. The last printed digit 1s rounded. appears without a number 


following it, no decimal point is 
printed. 
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Table R.4 (continued) 


Type Meaning Default 

f The precision value specifies the number Default precision is 6; if 
of digits after the decimal point. If a precision is Q, or if the period (.) 
decimal point appears, at least one digit appears without anumber 
appears before it. The value is rounded to following it, no decimal point is 
the appropriate number of digits. printed. 

g The precision specifies the maximum Six significant digits are printed, 

G number of significant digits printed. with any trailing zeros truncated. 

c The precision has no effect. Character is printed. 

S The precision specifies the maximum Characters are printed until a 
number of characters to be printed. null character is encountered. 
Characters in excess of precision are not 
printed. 


If the argument corresponding to a floating-point specifier is infinite, indefinite, or 
not a number (NAN), the printf function gives the following output: 


Value Output 

+ infinity 1.4INFrandom-digits 

— infinity —1.#INFrandom-digits 
Indefinite digit#INDrandom-digits 
NAN digit##NANrandom-digits 


Size and Distance Specification 

For printf, the format specification fields F and N refer to the “distance” to the 
object being read (near or far), and h and I refer to the “size” of the object being 
read (16-bit short or 32-bit long). The following list clarifies this use of F, N, h, 1, 


and L: 

Program Code Action 

printf (""%Ns"); Print near string 

printf ('%Fs"); Print far string 

printf ("'% Nn"); Store char count in near int 
printf (''% Fn"); Store char count in far int 
printf (""%hp"); Print a 16-bit pointer (xxxx) 
printf (''%lp"); Print a 32-bit pointer (xxxx:xxxx) 
printf (" % Nhn"); Store char count in near short int 
printf ("'%NIn"); Store char count in near long int 
printf (""%Fhn"); Store char count in far short int 


printf (''% Fin"); Store char count in far int 


Return Value 


Compatibility 


See Also 


Example 
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The specifications " %hs" and "'%l1s" are meaningless to printf. The specifica- 
tions "%Np" and "%Fp"' are aliases for "%hp" and '"%lp"' for the sake of com- 
patibility with Microsoft C version 4.0. 


The printf function returns the number of characters printed, or a negative value 
in the case of an error. 


Standards: ANSI, UNIX 
16-Bit: DOS, QWIN 
32-Bit: DOS32X 


{fprintf, scanf, sprintf, vfprintf, vprintf, vsprintf 


/* PRINTF.C illustrates output formatting with printf. */ 


dFinclude <stdio.h> 


void main(€ void ) 


{ 


char ch = ‘h', *string = "computer"; 
int count = -9234; 
double fp = 251.7366; 


/* Display integers. */ 

printf( "Integer formats:\n" 
"\tDecimal: 42d Justified: %.6d Unsigned: %u\n", 
count, count, count, count ); 


printf( "Decimal 4d as:\n\tHex: %Xh C hex: @x%x Octal: %4o\n", 
count, count, count, count ); 


/* Display in different radixes. */ 
printf( "Digits 10 equal:\n\tHex: %i Octal: %i Decimal: %i\n", 
Qx10, 010, 10 ); 


/* Display characters. */ 
printf( "Characters in field: \n%10@c BOCKN 5 CRs Ch) 


/* Display strings. */ 
printf( "Strings in field:\n%25s\n%25.4s\n", string, string ); 


/* Display real numbers. */ 
printf( “Real numbers: \n\t%f of me PEM! 5. CP Dy Dy ts: FDS 
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/* Display pointers. */ 
printf( "Address as:\n\tDefault: Zp Near: ZNp Far: %Fp\n", 
&count, (int __near *)&count, (int __far *)&count ); 


/* Count characters printed. */ 

printf( "Display to here:\n" ); 

printf( "1234567890123456%n/8901234567890\n", &count ); 
printf( "\tNumber displayed: %d\n\n", count ); 


Integer formats: 
Decimal: -9234 Justified: -009234 Unsigned: 56302 
Decimal -9234 as: 
Hex: DBEEh C hex: @xdbee Octal: 155756 
Digits 10 equal: 
Hex: 16 Octal: 8 Decimal: 10 
Characters in field: 
h h 
Strings in field: 
computer 
comp 
Real numbers: 
251.736600 251.74 2.517366e+002 2.517366E+002 
Address as: 
Default: 141C Near: 141C Far: @Q87:141C 
Display to here: 
123456789012345678901234567890 
Number displayed: 16 


Description 


Remarks 


Return Value 


Compatibility 


See Also 
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putc, putchar 


Writes a character to a stream (putc) or to stdout (putchar). 
#include <stdio.h> 


int pute( int c, FILE *stream ); 


int putchar( int c ); 


C Character to be written 


stream Pointer to FILE structure 


The pute routine writes the single character c to the output stream at the current 
position. The putchar routine is identical to pute(c, stdout). 


These routines are implemented as both macros and functions. See “Choosing 
Between Functions and Macros” on page 9 for a discussion of how to select 
between the macro and function forms. 


The pute and putchar routines return the character written, or EOF in the case of 
an error. Any integer can be passed to putc, but only the lower 8 bits are written. 


putc 

Standards: ANSI, UNIX 

16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 

putchar 

Standards: ANSI, UNIX 

16-Bit: DOS, QWIN 

32-Bit: DOS32X 


fputc, _fputchar, getc, getchar 
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Example /* PUTC.C: This program uses putc to write buffer to a stream. 
* If an error occurs, the program will stop before writing the 
* entire buffer. 
* / 


dAinclude <stdio.h> 


void main( void ) 

{ 
FILE *stream; 
char *p, buffer[] = "This is the line of output\n"; 
int ch; 


/* Make standard out the stream and write to it. */ 

stream = stdout; 

for( p buffer; (ch != EOF) && (*p != '\@"); ptt ) 
ch = putc( *p, stream ); 


Output This is the line of output 


Description 


Remarks 


Return Value 


_putch 
_ putch 
Writes a character to the console. 
#include <conio.h> Required only for function declarations 
int _ putch( int c ); 
C Character to be output 


The _ putch function writes the character c directly (without buffering) to the 
console. 


The function returns c if successful, and EOF if not. 


Compatibility Standards: None 
16-Bit: DOS 
32-Bit: DOS32X 
See Also _ceprintf, _ getch, _ getche 


Example 


/* GETCH.C: This program reads characters from the keyboard until it 
* receives a 'Y' or ‘y'. 
* / 


d#Ainclude <conio.h> 
#Hinclude <ctype.h> 


void main( void ) 
{ 
TInt ens 


_cputs( "Type 'Y' when finished typing keys: " ); 
do 
{ 

ch = _getch(); 

ch = toupper( ch ); 


} while( ch != 'Y' ); 

TPUVCME “Chi-J:s 

_putch( ‘\r'" ); /* Carriage return */ 
~putcn’ “Vn. /* Line feed « / 
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Output Type 'Y' when finished typing keys: Y 
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_ putenv 


Description Creates new environment variables; modifies or removes existing ones. 
#include <stdlib.h> Required only for function declarations 
int _ putenv( char “envstring ); 


envstring Environment-string definition 


Remarks The _ putenv function adds new environment variables or modifies the values of 
existing environment variables. Environment variables define the environment in 
which a process executes (for example, the default search path for libraries to be 
linked with a program). 


The envstring argument must be a pointer to a string with the form 
varname=string 


where varname is the name of the environment variable to be added or modified 
and string is the variable’s value. If varname is already part of the environment, its 
value is replaced by string; otherwise, the new varname variable and its string 
value are added to the environment. A variable can be removed from the environ- 
ment by specifying an empty string—that is, by specifying only varname=. 


This function affects only the environment that is local to the currently running 
process; it cannot be used to modify the command-level environment. When the 
currently running process terminates, the environment reverts to the level of the 
parent process (in most cases, the operating system level). However, the environ- 
ment affected by _ putenv can be passed to any child processes created by 

_ Spawn, _ exec, or system, and these child processes get any new items added by 
_ putenv. 


Never free a pointer to an environment entry, because the environment variable 
will then point to freed space. A similar problem can occur if you pass _ putenv a 
pointer to a local variable, then exit the function in which the variable is declared. 


The _ putenv function operates only on data structures accessible to the run-time 
library and not on the environment “segment” created for a process by the operat- 
ing system. 


598 _putenv 


Note that environment-table entries must not be changed directly. If an entry must 
be changed, use _ putenv. To modify the returned value without affecting the en- 
vironment table, use _strdup or strepy to make a copy of the string. 


The getenv and _ putenv functions use the global variable environ to access the 

environment table. The _ putenv function may change the value of environ, thus 
invalidating the envp argument to the main function. Therefore, it is safer to use 

the environ variable to access the environment information. 


Return Value The _ putenv function returns 0 if it is successful. A return value of —1 indicates 
an error. 

Compatibility Standards: UNIX 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 
Use _putenv for compatibility with ANSI naming conventions of non-ANSI func- 
tions. Use putenv and link with OLDNAMES.LIB for UNIX compatibility. 

See Also getenv, _searchenv 

Example /* GETENV.C: This program uses getenv to retrieve the LIB environment 


* variable and then uses _putenv to change it to a new value. 
 / 


#include <stdlib.h> 
#Finclude <stdio.h> 


void main( void ) 
{ 


char *libvar; 


/* Get the value of the LIB environment variable. */ 
libvar = getenv( "LIB" ); 
if( Jibvar != NULL ) 

printf( "Original LIB variable is: %s\n", libvar ); 


/* Attempt to change path. Note that this only affects the environment 
* variable of the current process. The command processor's environment 
* 71S not changed. 

x / 
_putenv( “"LIB=c:\\mylib;c:\\yourlib" ); 


/* Get new value. */ 
libvar = getenv( "LIB" ); 
if( libvar != NULL ) 
printf( "New LIB variable is: %s\n", libvar ); 
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Output Original LIB variable is: C:\LIB 
New LIB variable is: c:\mylib;c:\yourlib 


600 _ putimage Functions 


Description 


Remarks 


_ putimage Functions 


Retrieve images from a buffer. 
#include <graph.h> 


void __ far _ putimage( short x, short y, const char __ huge *image, 
short action ); 


void __far _ putimage_w( double wx, double wy, const char __ huge “image, 
short action ); 


x,y Position of upper-left corner of image 
image Stored image buffer 

action Interaction with existing screen image 
wx, Wy Position of upper-left corner of image 


The _ putimage function transfers to the screen the image stored in the buffer that 
image points to. 


In the _ putimage function, the upper-left corner of the image is placed at the view 
coordinate point (x, y). In the _ putimage_ w function, the upper-left corner of the 
image is placed at the window coordinate point (wx, wy). 


The action argument defines the interaction between the stored image and the one 
that is already on the screen. It may be any one of the following manifest constants 
(defined in GRAPH.H): 


Constant Meaning 


_GAND Transfers the image over an existing image on the screen. The 
resulting image is the logical-AND product of the two images: 
points that had the same color in both the existing image and the 
new one will remain the same color, while points that have 
different colors are joined by logical-AND. 


_GOR Superimposes the image onto an existing image. The new image 
does not erase the previous screen contents. 


_GPRESET Transfers the data point-by-point onto the screen. Each point has 
the inverse of the color attribute it had when it was taken from 
the screen by _ getimage, producing a negative image. 


Return Value 


Compatibility 


See Also 


Example 


_ putimage Functions 


Constant Meaning 


_GPSET Transfers the data point-by-point onto the screen. Each point has 
the exact color attribute it had when it was taken from the screen 
by _ getimage. 


_GXOR Causes the points on the screen to be inverted where a point 
exists in the image buffer. This behavior is like that of the 
cursor: when an image is put against a complex background 
twice, the background is restored unchanged. This allows you to 
move an object around without erasing the background. The 
_GXOR constant is a special mode often used for animation. 


None. Use the _ grstatus function to check the result of a call to the _ putimage 
functions. 


Standards: None 
16-Bit: DOS 
32-Bit: None 


_getimage, _grstatus, _imagesize 


See the example for _ getimage. 


601 


602 puts 


Description 


Remarks 


Return Value 


Compatibility 


See Also 


puts 


Writes a string to stdout. 
#include <stdio.h> 
int puts( const char *string ); 


string String to be output 


The puts function writes string to the standard output stream stdout, replacing the 
string’s terminating null character (’\0’) with a newline character (\n) in the output 
stream. 


The puts function returns a nonnegative value if it is successful. If the function 
fails, it returns EOF. 


Standards: ANSI, UNIX 


16-Bit: DOS, QWIN 
32-Bit: DOS32X 
fputs, gets 


Example /* PUTS.C: This program uses puts to write a string to stdout. */ 


4#Ainclude <stdio.h> 


void main( void ) 


{ 
puts( "Hello world from puts!" ); 
} 


Output Hello world from puts! 
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Description Writes an integer to a stream. 


#include <stdio.h> 


int _ putw( int binint, FILE *stream ); 


binint Binary integer to be output 
stream Pointer to FILE structure 
Remarks The _ putw function writes a binary value of type int to the current position of 


stream. The _ putw function does not affect the alignment of items in the stream, 
nor does it assume any special alignment. 


The _ putw function is provided primarily for compatibility with previous librar- 
ies. Note that portability problems may occur with _ putw, since the size of an int 
and ordering of bytes within an int differ across systems. 


Return Value The _ putw function returns the value written. A return value of EOF may indi- 
cate an error. Since EOF is also a legitimate integer value, ferror should be used 
to verify an error. 


Compatibility Standards: UNIX 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 


Use _ putw for compatibility with ANSI naming conventions of non-ANSI func- 
tions. Use putw and link with OLDNAMES.LIB for UNIX compatibility. 


See Also _getw 
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Example 


Output 


_ putw 


/* PUTW.C: This program uses _putw to write a word to a stream, 
* then performs an error check. 
*« / 


#include <stdio.h> 
#Finclude <stdlib.h> 


void main( void ) 


{ 
FILE *stream; 
unsigned u; 
if( (stream = fopen( "data.out", "wb" )) == NULL ) 
exit( 1 ); 
for( u = @; u < 10; ut++ ) 
{ 
_putw( u + Qx2132, stdout ); 
_putw( u + @x2132, stream ); /* Write word to stream. */ 
if( ferror( stream ) ) /* Make error check. */ 
{ 
printf( "_putw failed” ); 
clearerr( stream ); 
exit( 1 ); 
} 
} 
printf( "\nWrote ten words\n" ); 
fclose( stream ); 
} 


213141516! 71B8!9!131;! 
Wrote ten words 


Description 


Remarks 
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qsort 


Performs a quick sort. 


#include <stdlib.h> For ANSI compatibility 


#include <search.h> Required only for function declarations 


void gsort( void *base, size_t num, size_t width, 
int(___cdecl *compare ) ( const void *elem/, const void *elem2 ) )5 


base Start of target array 

num Array size in elements 

width Element size in bytes 

compare Comparison function 

elem! Pointer to the key for the search 

elem2 Pointer to the array element to be compared with 
the key 


The qsort function implements a quick-sort algorithm to sort an array of num ele- 
ments, each of width bytes. The argument base is a pointer to the base of the array 
to be sorted. The qsort function overwrites this array with the sorted elements. 


The argument compare is a pointer to a user-supplied routine that compares two 
array elements and returns a value specifying their relationship. The qsort func- 
tion calls the compare routine one or more times during the sort, passing pointers 
to two array elements on each call: 


compare( (void *) elem1, (void *) elem2 ); 


The routine must compare the elements, then return one of the following values: 


Value Meaning 

<0 elem! less than elem2 

=0 elem! equivalent to elem2 
>0 elem! greater than elem2 


The array is sorted in increasing order, as defined by the comparison function. To 
sort an array in decreasing order, reverse the sense of “greater than” and “less 
than” in the comparison function. 


606 qsort 


Return Value None. 

Compatibility Standards: ANSI, UNIX 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 

See Also bsearch, _lsearch 


Example /* QSORT.C: This program reads the command-line parameters and 
* uses qsort to sort them. It then displays the sorted arguments. 
a / 


dinclude <stdlib.h> 
#tinclude <string.h> 
dAinclude <stdio.h> 


int compare( void *argl, void *arg2 ); /* Prototype */ 


void main( int argc, char **argv ) 


{ 
int i; 
/* Eliminate argvl@] from sort: */ 
argvt++; 
argc-; 
/* Sort remaining args using Quicksort algorithm: */ 
qsort( (void *)argv, (size_t)argc, sizeof( char * ), compare ); 
/* Output sorted list: */ 
for( i = @; i < argc; ++i ) 
printf( "%s ", argvli] ); 
printf( “\n" ); 
} 
int compare( void *argl, void *arg2 ) 
{ 
/* Compare all of both strings: */ 
return _stricmp( * ( char** ) argl, * ( char** ) arg2 ); 
} | 
Output [C:\LIBREF] qsort Rosey good boy deserves favor 


boy deserves every favor good 


Description 


Remarks 


Return Value 


raise 


Sends a signal to the executing program. 


#include <signal.h> 


int raise( int sig ); 


Sig 


Signal to be raised 
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The raise function sends sig to the executing program. If a signal-handling routine 
for sig has been installed by a prior call to signal, raise causes that routine to be 
executed. If no handler routine has been installed, the default action (as listed 


below) is taken. 


The signal value sig can be one of the following manifest constants: 


Signal 
SIGABRT 


SIGFPE 


SIGILL 


SIGINT 
SIGSEGV 


SIGTERM 


Meaning 


Abnormal termination. 
Floating-point error. 


[legal instruction. This signal is not 
generated by DOS, but is supported 
for ANSI compatibility. 


CTRL+ C interrupt. 


Illegal storage access. This signal 1s 
not generated by DOS, but is 
supported for ANSI compatibility. 


Termination request sent to the 
program. This signal is not 
generated by DOS, but is supported 
for ANSI compatibility. 


Default 
Terminates the calling 
program with exit code 3. 


Terminates the calling 
program. 


Terminates the calling 
program. 


Issues INT23H. 


Terminates the calling 
program. 


Ignores the signal. 


If successful, the raise function returns 0. Otherwise, it returns a nonzero value. 
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Compatibility Standards: ANSI 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 

See Also abort, signal 


Example See the example for signal. 
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rand 


Description Generates a pseudorandom number. 


#include <stdlib.h> Required only for function declarations 


int rand( void ); 


Remarks The rand function returns a pseudorandom integer in the range 0 to 
RAND_ MAX. The srand routine can be used to seed the pseudorandom-number 
generator before calling rand. 


Return Value The rand function returns a pseudorandom number, as described above. There is 
no error return. 


Compatibility Standards: ANSI, UNIX 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 

See Also srand 


Example /* RAND.C: This program seeds the random-number generator with the 
* time, then displays 20 random integers. 
* / 


deinclude <stdlib.h> 
deinclude <stdio.h> 
d#Finclude <time.h> 


void main( void ) 
{ 


int i; 


/* Seed the random-number generator with current time so that 
* the numbers will be different every time we run. 

« / 

srand( (unsigned)time( NULL ) ); 


/* Display 10 numbers. */ 
FOr. WV = Os 1 << 10s Te) 
printf( " %6d\n", rand() ); 
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Output 


rand 


19471 
16395 

8268 
15582 

6489 
28356 
27042 

5276 
23070 
10930 


Description 


Remarks 


Return Value 


_read 611 
_read 
Reads data from a file. 
#include <io.h> Required only for function declarations 


int _read( int handle, void *buffer, unsigned int count ); 


handle Handle referring to open file 
buffer Storage location for data 
count Maximum number of bytes 


The _read function attempts to read count bytes into buffer from the file as- 
sociated with handle. The read operation begins at the current position of the file 
pointer associated with the given file. After the read operation, the file pointer 
points to the next unread character. 


The _read function returns the number of bytes actually read, which may be less 
than count if there are fewer than count bytes left in the file, or if the file was 
opened in text mode (see below). The return value 0 indicates an attempt to read at 
end-of-file. The return value —1 indicates an error, and errno is set to the follow- 
ing value: 


Value Meaning 


EBADF The given handle is invalid; or the file is not open for reading; or 
(DOS versions 3.0 and later) the file is locked. 


For 16-bit platforms, if you are reading more than 32K (the maximum size for 
type int) from a file, the return value should be of type unsigned int (see the ex- 
ample that follows). However, the maximum number of bytes that can be read 
from a file in one operation is 65,534, since 65,535 (or OXFFFF) is indistinguisha- 
ble from —1, and therefore cannot be distinguished from an error return. 


If the file was opened in text mode, the return value may not correspond to the 
number of bytes actually read. When text mode 1s in effect, each carriage-return— 
line-feed (CR-LF) pair is replaced with a single line-feed character. Only the single 
line-feed character is counted in the return value. The replacement does not affect 
the file pointer. 
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_ read 


Compatibility 


See Also 


Example 


Output 


Note that when files are opened in text mode, a CTRL+Z character is treated as an 
end-of-file indicator. When the CTRL+Z is encountered, the read terminates, and the 
next read returns O bytes. The _Iseek function will clear the end-of-file indicator. 


Standards: UNIX 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 


Use _read for compatibility with ANSI naming conventions of non-ANSI func- 
tions. Use read and link with OLDNAMES.LIB for UNIX compatibility. 


_creat, fread, _ open, _ write 


/* READ.C: This program opens a file named READ.C and tries to read 60,000 
* bytes from that file using read. It then displays the actual 
* number of bytes read from READ.C. 


* / 


#Hinclude <fcnt1.h> /* Needed only for _O_RDWR definition */ 
fHinclude <io.h> 

fHinclude <stdlib.h> 

#Hinclude <stdio.h> 


char buffer[60000]; 


void main( void ) 


{ 
int fh; 
unsigned int nbytes = 60000, bytesread; 
/* Open file for input: */ 
if( (fh = _open( “read.c", _O_RDONLY )) == -1 ) 
{ 
perror( “open failed on input file” ); 
exit( 1 ); 
} 
/* Read in input: */ 
if( ( bytesread = _read( fh, buffer, nbytes ) ) <= @ ) 
perror( "Problem reading file" ); 
else 
printf( "Read %u bytes from file\n", bytesread ); 
_close( fh ); 
} 


Read 7/47 bytes from file 


Description 


Remarks 
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realloc Functions 


Reallocate memory blocks. 


#include <stdlib.h> For ANSI compatibility (realloc only) 


#include <malloc.h> Required only for function declarations 


void *realloc( void *memblock, size_t size )5 


void __ based( void ) *_brealloc( __ segment seg, 
void __ based( void ) *memblock, size_t size )3 


void __ far *_frealloc( void __ far *memblock, size_t size ); 


void __ near *_nrealloc( void __near *memblock, size_t size )3 


memblock Pointer to previously allocated memory block 
size New size in bytes 
seg Segment selector 


The realloc family of functions changes the size of a previously allocated memory 
block. The memblock argument points to the beginning of the memory block. If 
memblock is NULL (_NULLOFF for _ brealloc), realloc functions in the same 
way as malloc and allocates a new block of size bytes. If memblock is not NULL 
(_NULLOFF for _ brealloc), it should be a pointer returned by a prior call to 
calloc, malloc, or realloc. 


The size argument gives the new size of the block, in bytes. The contents of the 
block are unchanged up to the shorter of the new and old sizes, although the new 
block may be in a different location. 


In large data models (that is, compact-, large-, and huge-model programs), realloc 
maps to _frealloc. In small data models (tiny-, small-, and medium-model pro- 
grams), realloc maps to _nrealloc. 
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Return Value 


Compatibility 


See Also 


The various realloc functions reallocate memory in the heap as specified in the 
following list: 


Function Heap 

realloc Depends on data model of program 
_brealloc Based heap specified by seg value 
_frealloc Far heap (outside default data segment) 
_nrealloc Near heap (inside default data segment) 


The realloc functions return a void pointer to the reallocated (and possibly 
moved) memory block. 


The return value is NULL (_NULLOFF for _ brealloc) if the size is zero and the 
buffer argument is not NULL (_NULLOFF for _brealloc), or if there is not 
enough available memory to expand the block to the given size. In the first case, 
the original block is freed. In the second, the original block is unchanged. 


The storage space pointed to by the return value is guaranteed to be suitably 
aligned for storage of any type of object. To get a pointer to a type other than void, 
use a type cast on the return value. 


realloc 

Standards: ANSI, UNIX 

16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 


_brealloc, _frealloc, _ nrealloc 


Standards: None 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: None 


calloc functions, free functions, malloc functions 


Example 


Output 
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REALLOC.C: This program allocates a block of memory for buffer 
and then uses _msize to display the size of that block. Next, it 
uses realloc to expand the amount of memory used by buffer 

and then calls _msize again to display the new amount of 

memory allocated to buffer. 


dFinclude <stdio.h> 
d4Finclude <malloc.h> 
d#Hinclude <stdlib.h> 


void main( void ) 


{ 


long *buffer; 
size_t size; 


if( (buffer = (long *)malloc( 1000 * sizeof( long ) )) == NULL ) 
Ax Ut. ab 4 


size = _msize( buffer ); 
printf( "Size of block after malloc of 100@ longs: %4u\n", size ); 


/* Reallocate and show new size: */ 


if( (buffer = realloc( buffer, size + (1000 * sizeof( long )) )) == NULL ) 
exit( 1 ); 
size = _msize( buffer ); 


printf( "Size of block after realloc of 1000 more longs: Zu\n", size ); 


free( buffer ); 
exit( @ ); 


Size of block after malloc of 1000 longs: 4000 
Size of block after realloc of 1000 more longs: 8000 


616  _ rectangle Functions 


Description 


Remarks 


_ rectangle Functions 


Draw rectangles. 
#include <graph.h> 


short __ far _rectangle( short control, short x/, short y/, short x2, short y2 ); 


short __far _ rectangle_ w( short control, double wx/, double wy/, double wx2, 
double wy2 ); 


short __ far _rectangle_ wxy( short control, struct _ wxycoord __ far *pwxy/, 
struct _wxycoord __ far *pwxy2 ); 


control Fill flag 

xl, yl Upper-left corner 
x2, y2 Lower-right corner 
wxl, wyl Upper-left corner 
wx2, wy2 Lower-right corner 
pwxyl Upper-left corner 
pwxy2 Lower-right corner 


The _rectangle functions draw a rectangle with the current line style. The 
_rectangle function uses the view coordinate system. The view coordinate points 
(xl, yl) and (x2, y2) are the diagonally opposed corners of the rectangle. 


The _rectangle_w function uses the window coordinate system. The window 
coordinate points (wx/, wy/) and (wx2, wy2) are the diagonally opposed corners of 
the rectangle. 


The _rectangle_ wxy function uses the window coordinate system. The window 
coordinate points (pwxy/) and (pwxyZ2) are the diagonally opposed corners of the 
rectangle. The coordinates for the _rectangle_wxy routine are given in terms of 
an _ wxycoord structure (defined in GRAPH.H), which contains the following 
elements: 


Element Description 


double wx window x coordinate 
double wy window y coordinate 


_ rectangle Functions 


The control parameter can be one of the following manifest constants: 


Constant Action 


_GFILLINTERIOR _ Fills the figure, using a scanfill algorithm, with the current 
color using the current fill mask 


_GBORDER Does not fill the rectangle 


If the current fill mask is NULL, no mask is used. Instead, the rectangle is filled 
with the current color. 


If you try to fill the rectangle with the _ floodfill function, the rectangle must be 
bordered by a solid line-style pattern. 


Return Value The function returns a nonzero value if the rectangle is drawn successfully, or 0 
if not. 

Compatibility Standards: None 
16-Bit: DOS 
32-Bit: None 

See Also _arc functions, _ ellipse functions, _floodfill, _getcolor, _lineto functions, 
_pie functions, _polygon, _setcolor, _ setfillmask 

Example /* RECT.C: This program draws a rectangle. */ 


#Hinclude <conio.h> 
fHinclude <stdlib.h> 
#include <graph.h> 


void main( void ) 
{ 
/* Find a valid graphics mode. */ 
if( !_setvideomode( _MAXRESMODE ) ) 
exit( 1 ); 


_rectangle( _GBORDER, 8@, 50, 240, 150 ); 
SgetcnO: 


_setvideomode( _DEFAULTMODE ); 
} 
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618  _registerfonts 


Description 


Remarks 


Return Value 


Compatibility 


See Also 


Example 


_registerfonts 


Initializes the fonts graphics system. 
#include <graph.h> 
short __ far _registerfonts( const char __ far “pathname ); 


pathname Path name specifying .FON files to be registered 


The _registerfonts function initializes the fonts graphics system. Font files must 
be registered with the _registerfonts function before any other font-related library 
function (_ getgtextextent, _ outgtext, _setfont, _unregisterfonts) can be used. 


The _registerfonts function reads the specified files and loads font header infor- 
mation into memory. Each font header takes up about 140 bytes of memory. 


The pathname argument is the path specification and filename of valid .FON files. 
The pathname can contain standard DOS wildcards. 


The font functions affect only the output from the font output function _ outgtext, 
no other run-time output functions are affected by font usage. 


The _registerfonts function returns a positive value which indicates the number 
of fonts successfully registered. A negative return value indicates failure. The 
following negative values may be returned: 


Value Meaning 

—1 No such file or directory. 

—2 One or more of the .FON files was not a valid, binary .FON file. 
—3 One or more of the .FON files is damaged. 


Standards: None 
16-Bit: DOS 
32-Bit: None 


_getfontinfo, _ getgtextextent, _grstatus, _outgtext, _setfont, 
_unregisterfonts 


See the example for _ outgtext. 


_remapallpalette, remappalette 619 
_remapallpaletie, remappalette 
Description Remap palette colors. 
#include <graph.h> 


short __ far _remapallpalette( long __ far *colors ); 


long __ far _remappalette( short index, long color ); 


colors Color value array 
index Color index to reassign 
color Color value to assign color index to 
Remarks The _remapallpalette function remaps the entire color palette simultaneously to 


the colors given in the colors array. The colors array is an array of long integers 
where the size of the array varies from 16 to 64 to 256, depending on the video 
mode. The number of colors mapped depends on the number of colors supported 
by the current video mode. The _ remapallpalette function works in all video 
modes (except _ORESCOLOR mode), but only with EGA, MCGA, VGA, or 


SVGA hardware. 

The default color values for color text or a 16-color graphics mode are shown 
below: 

Number Color Number Color 

0 Black 8 Dark gray 

1 Blue 9 Light blue 

2 Green 10 Light green 

3 Cyan 11 Light cyan 

4 Red 12 Light red 

> Magenta 13 Light magenta 
6 Brown 14 Yellow 

i White 13 Bright white 


The first array element specifies the new color value to be associated with 

color index 0 (the background color in graphics modes). After the call to 
_remapallpalette, calls to _setcolor will index into the new array of colors. 
The mapping done by _remapallpalette affects the current display immediately. 
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_remapallipalette, remappalette 


The colors array can be larger than the number of colors supported by the current 
video mode, but only the first n elements are used, where n is the number of colors 
supported by the current video mode, as indicated by the numcolors element of 
the _ videoconfig structure. 


The long color value is defined by specifying three bytes of data representing the 
three component colors: red, green, and blue. 


Each of the three bytes represents the intensity of one of the red, green, or blue 
component colors, and must be in the range 0-31. In other words, the low-order 
six bits of each byte specify the component’s intensity and the high-order two bits 
should be zero. The fourth (high-order) byte in the long is unused and should be 
set to zero. The diagram below shows the ordering of bytes within the long value. 


For example, to create a lighter shade of blue, start with lots of blue, add some 
green, and maybe a little bit of red. The three-byte color value would be: 


blue byte green byte red byte 
QQ0011111 00101111 00011111 
high ————————————-»_ low order 


Manifest constants are defined in GRAPH.H for the default color values corre- 
sponding to color indices 0-15 in color text modes and 16-color graphics modes, 
as shown below: 


Index Constant Index Constant 

0 _BLACK 8 _GRAY 

1 _BLUE 9 _LIGHTBLUE 

2 _GREEN 10 _LIGHTGREEN 

5 _CYAN 1] _LIGHTCYAN 

4 _RED 12 _LIGHTRED 

> _MAGENTA 13 _LIGHTMAGENTA 
6 _BROWN 14 _YELLOW 

7 


_WHITE 15 _BRIGHTWHITE 


The VGA supports a palette of 262,144 (256K) colors in color modes, and the 
EGA supports a palette of only 64 different colors. Color values for EGA are 
specified in exactly the same way as with the VGA; however, the low-order four 
bits of each byte are simply ignored. 


The _remappalette function assigns a new color value color to the color index 
given by index. This remapping affects the current display immediately. 


The _remappalette function works in all graphics modes, but only with EGA, 
MCGA, VGA, or SVGA hardware. An error results if the function is called while 
using any other configuration. 


_remapallpalette, remappalette 621 


Return Value 


Compatibility 


See Also 


Example 


The color value used in _remappalette is defined and used exactly as noted above 
for _remapallpalette. The range of color indices used with _remappalette de- 
pends on the number of colors supported by the video mode. 


The _ remapallpalette and _remappalette functions do not affect the presenta- 
tion-graphics “palettes,” which are manipulated with the _ pg_ getpalette, 
_pg_setpalette, and _ pg_resetpalette functions. 


If a VGA or MCGA adapter is connected to an analog monochrome monitor, the 
color value is transformed into its gray-scale equivalent, based on the weighted 
sum of its red, green, and blue components (30% red + 50% green + 11% blue). 


If successful, _remapallpalette returns nonzero value (short). In case of an error, 
_remapallpalette returns 0 (short). 


If successful, _remappalette returns the color value previously assigned to index, 
or —1 if the function is inoperative (not EGA, VGA, SVGA, or MCGA), or if the 
color index is out of range. Note that _remapallpalette returns a short value and 
_remappalette returns a long value. 


Standards: None 
16-Bit: DOS 
32-Bit: None 


_getvideoconfig, _selectpalette, _setbkcolor, _setvideomode 


/* RMPALPAL.C: This example illustrates functions for assigning 


* color values to color indices. Functions illustrated include: 
_remappalette _remapallpalette 


#Hinclude <graph.h> 
dHinclude <conio.h> 
d#tinclude <stdio.h> 
4#Hinclude <stdlib.h> 


/* Macro for mixing Red, Green, and Blue elements of color */ 
#tdefine RGB(r,g,b) (((long) ((b) << 8 | (g)) << 8) | (r)) 


long tmp, pal[256]; 


void main( void ) 


{ 


short red, blue, green; 
short inc, i, mode, cells, x, y, xinc, yinc; 


buf l4@]; 


struct _videoconfig vc; 


622 _remapallpalette, remappalette 


/* Make sure all palette numbers are valid. */ 
fOr’ 1 SOs 1S. 2568: Ta) 
pallLi] = _BLACK; 


/* Loop through each graphics mode that supports palettes. */ 
for( mode = _MRES4COLOR; mode <= _MRES256COLOR; modet++ ) 
{ 
if( mode == _ERESNOCOLOR ) 
mode++; 
if( !_setvideomode( mode ) ) 
continue; 


/* Set variables for each mode. */ 
_getvideoconfig( &vc ); 
sSwitch( vc.numcolors ) 


{ 
case 256: /* Active bits in this order: * / 
cells = 13; 
inc = 12; /* 22222222 ??bbbbbb ??gggggg ??rrrrrr- */ 
break; 
case 16: 
cells = 4; 
if( (vc.mode == _ERESCOLOR) || (vc.mode == _VRESI16COLOR) ) 
Le 3S UG /* 22222222 22?bb?2?2?? 2?2?gg???? 2?rr2??? = */ 
else 
ANG = Ses /* 22222222 ?2?2?BbD?2?2? 2??2?Gg???? ?2?Rr???? = x*/ 
break; 
case 4; 
Celis: = 2; 
Ine -=:32s /* 22222222 22?Bb??2?? 2?2?Gg???? ?2??Rr???? = x*/ 
break; 
default: 
continue; 
} 
Xinc = vc.numxpixels / cells; 
yinc = vc.numypixels / cells; 


/* Fill palette arrays in BGR order. */ 
for( i = @, blue = 0; blue < 64; blue += inc ) 
for( green = 0; green < 64; green += inc ) 
for( red = @; red < 64; red += inc ) 
{ 
palLi] = RGB( red, green, blue ); 
/* Special case of using 6 bits to represent 16 colors. 
* If both bits are on for any color, intensity is set. 
* If one bit is set for a color, the color is on. 
* / 
if( inc == 3 
palLi + 8 
j++; 


2) 
] = palli] | (palLi] >> 1); 


_remapallpalette, remappalette 623 


/* If palettes available, remap all palettes at once. */ 
if( !_remapallpalette( pal ) ) 


{ 
_setvideomode( _DEFAULTMODE ); 
_outtext( "Palettes not available with this adapter" ); 
exit’ 1:4 

} 


/* Draw colored squares. */ 
for( i = @, x = @; x < ( xine * cells ); x += xinc ) 
for( y = @; y < ( yine * cells); y += yinc ) 
{ 
_setcolor( i++ ); 
_rectangle( _GFILLINTERIOR, x, y, x + xinc, y + yinc ); 
} 


/* Note that for 256-color mode, not all colors are shown. The number 
* of colors from mixing three base colors can never be the same as 
* the number that can be shown on a two-dimensional grid. 
* / 
Sprintf( buf, “Mode 4d has 4d colors", vc.mode, vc.numcolors ); 
_setcolor( vce.numcolors / 2 ); 
_outtext( buf ); 
_getch(); 


/* Change each palette entry separately in GRB order. */ 
for( i = 0, green = 0; green < 64; green += inc ) 
for( red = @; red < 64; red += inc ) 
for(blue = @; blue < 64; blue += inc ) 
i 
tmp = RGBC red, green, blue ); 
_remappalette( i, tmp ); 
LPG Ane cS= 32/9 
_remappalette( i + 8, tmp | (tmp >> 1) ); 
jets 
} 
=getchnt): 
} 
_setvideomode( _DEFAULTMODE ); 
exit( @ ); 
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Description 


Remarks 


Return Value 


Compatibility 


See Also 


Example | 


remove 


Deletes a file. 


#include <stdio.h> Required for ANSI compatibility 
#include <io.h> Use either IO.H or STDIO.H 


int remove( const char *path ); 


path Path name of file to be removed 


The remove function deletes the file specified by path. 


The function returns 0 if the file is successfully deleted. Otherwise, it returns —1 
and sets errno to one of these values: 


Value Meaning 

EACCES Path name specifies a read-only file. 

ENOENT File or path name not found, or path name specifies a directory. 
Standards: ANSI 

16-Bit: DOS, QWIN, WIN, WIN DLL 

32-Bit: DOS32X 

_ unlink 


/* REMOVE.C: This program uses remove to delete REMOVE.OBJU. */ 


d#Ainclude <stdio.h> 


Output 


void main( void ) 


{ 
if( remove( "remove.obj" ) == -1 ) 
perror( "Could not delete 'REMOVE.OBU'" ); 
else 
printf( "Deleted "REMOVE.OBJ'\n" ); 
i 


Deleted "REMOVE.OBJ' 


Description 


Remarks 


Return Value 


Compatibility 
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rename 


Renames a file or directory. 


#include <stdio.h> Required for ANSI compatibility 
#include <io.h> Use either IO.H or STDIO.H 


int rename( const char *oldname, const char *newname ); 


oldname Pointer to old name 


newname Pointer to new name 


The rename function renames the file or directory specified by oldname to the 
name given by newname. The old name must be the path name of an existing file 
or directory. The new name must not be the name of an existing file or directory. 


The rename function can be used to move a file from one directory to another by 
giving a different path name in the newname argument. However, files cannot be 
moved from one device to another (for example, from drive A to drive B). Directo- 
ries can only be renamed, not moved. 


The rename function returns 0 if it is successful. On an error, it returns a nonzero 
value and sets errno to one of the following values: 


Value Meaning 


EACCES File or directory specified by newname already exists or could 
not be created (invalid path); or oldname is a directory and 
newname specifies a different path. 


ENOENT File or path name specified by oldname not found. 
EXDEV Attempt to move a file to a different device. 


Standards: ANSI 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 
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Example /* RENAMER.C: This program attempts to rename a file named RENAMER.OBJ to 
* RENAMER.JBO. For this operation to succeed, a file named RENAMER.OBJ 


* must exist and a file named RENAMER.JBO must not exist. 
* / 


dAinclude <stdio.h> 


void main( void ) 
{ 
int result; | 
char old[] = "RENAMER.OBJ", newL] = "RENAMER.JBO"; 


/*x Attempt to rename file: */ 
result = rename( old, new ); 
if( result != @ ) 
printf( "Could not rename '%s'\n", old ); 
else 
printf( "File '%s" renamed to '%s'\n", old, new ); 


Output File "RENAMER.OBJ' renamed to 'RENAMER.JBO' 


Description 


Remarks 


Return Value 


Compatibility 
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rewind 


Repositions the file pointer to the beginning of a file. 
#include <stdio.h> 
void rewind( FILE *stream ); 


stream Pointer to FILE structure 


The rewind function repositions the file pointer associated with stream to the 
beginning of the file. A call to rewind is equivalent to 


(void) fseek( stream, 0L, SEEK_SET ); 


except that rewind clears the error indicators for the stream, and fseek does not. 
Both rewind and fseek clear the end-of-file indicator. Also, fseek returns a value 
that indicates whether the pointer was successfully moved, but rewind does not re- 
turn any value. 


You can also use the rewind function to clear the keyboard buffer. Use the 
rewind function with the stream stdin, which is associated with the keyboard by 
default. | 


The rewind function has no return value. 


Standards: ANSI, UNIX 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 
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Example /* REWIND.C: This program first opens a file named REWIND.OUT for input 


* Output and writes two integers to the file. Next, it uses rewind to 
* reposition the file pointer to the beginning of the file and reads 
* the data back in. 


* / 


dFinclude <stdio.h> 


void main( void )— 


{ 
FILE *stream; 
int datal, data2; 
datal = 1; 
data2 = -37; 
if( (stream = fopen( "rewind.out", "wt" )) != NULL ) 
{ 
fprintf( stream, "%d 4d", datal, data2 ); 
printf( "The values written are: 4d and 4d\n", datal, data2 ); 
rewind( stream ); 
fscanf( stream, "%d 4d", &datal, &data2 ); 
printf( "The values read are: %d and %d\n", datal, data2 ); 
fclose( stream ); 
} 
} 
Output The values written are: 1 and -37 


The values read are: 1 and -3/7 


and 


Description 


Remarks 


Return Value 


Compatibility 


See Also 
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_ rmdir 


Deletes a directory. 
#include <direct.h> Required only for function declarations 
int _rmdir( char *dirname ); 


dirname Path name of directory to be removed 


The _rmdir function deletes the directory specified by dirname. The directory 
must be empty, and it must not be the current working directory or the root 
directory. 


The _rmdir function returns the value 0 if the directory is successfully deleted. A 
return value of —1 indicates an error, and errno is set to one of the following 
values: 

Value Meaning 


EACCES The given path name is not a directory; or the directory is not 
empty; or the directory is the current working directory or the 
root directory. 


ENOENT Path name not found. 


Standards: None 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 


_chdir, _ mkdir 
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Example /* MAKEDIR.C */ 
#include <direct.h> 
d#Finclude <stdlib.h> 
#Hinclude <stdio.h> 


void main( void ) 
{ 
int result; 


if( _mkdir( "\\testtmp"” ) == @ ) 


{ 
printf( "Directory '\\testtmp' was successfully created\n" ); 
system( "dir \\testtmp" ); 
if( _rmdir( "\\testtmp" ) == @ ) 
printf( "Directory '\\testtmp" was successfully removed\n"  ); 
else 
printf( "Problem removing directory ‘'\\testtmp'\n" ); 
} 
else 
printf( "Problem creating directory ‘\\testtmp'\n" ); 
} 
Output Directory '\testtmp' was successfully created 


The volume label in drive C is ZEPPELIN. 
Directory of C:\TESTTMP 


<DIR> 12-19-99 11:20a 
<DIR> 12-19-99 11:20a 
2 File(s) 12730368 bytes free 
Directory ‘'\testtmp' was successfully removed 
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_rmimp 


Description Removes temporary files. 
#include <stdio.h> 
int _rmtmp( void ); 

Remarks The _rmtmp function is used to clean up all the temporary files in the current 
directory. The function removes only those files created by tmpfile and should be 
used only in the same directory in which the temporary files were created. 

Return Value The _rmtmp function returns the number of temporary files closed and deleted. 

Compatibility Standards: None 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 

See Also _flushall, tmpfile, tmpnam 

Example /* TMPFILE.C: This program uses tmpfile to create a temporary file, 


* then deletes this file with _rmtmp. 
* / 


dAinclude <stdio.h> 


void main( void ) 

{ 
FILE *stream; 
char tempstringL] = "String to be written"; 
int: i 


/* Create temporary files. */ 
for( i=l; i <= 10; i++ ) 


if( (stream = tmpfile()) == NULL ) 
perror( "Could not open new temporary file\n" ); 
else 
printf( "Temporary file %d was created\n", i ); 
. 


/* Remove temporary files. */ 
printf( "%d temporary files deleted\n", _rmtmp() ); 
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Output Temporary file 
Temporary file 
Temporary file 
Temporary file 
Temporary file 
Temporary file 
Temporary file 7 was created 
Temporary file was created 
Temporary file 9 was created 
Temporary file 10 was created 
10 temporary files deleted 


was created 
was created 
was created 
was created 
was created 
was created 


COND OO BW PF 
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_rotl, _ rotr 


Description Rotate bits to the left (_rotl) or right (_rotr). 
#include <stdlib.h> 


unsigned int _ rotl( unsigned int value, int shift ); 


unsigned int _rotr( unsigned int value, int shift ); 


value Value to be rotated 
shift Number of bits to shift 


Remarks The _rotl and _rotr functions rotate the unsigned value by shift bits. The _ rotl 
function rotates the value left. The _rotr function rotates the value night. Both 
functions “wrap” bits rotated off one end of value to the other end. 


Return Value Both functions return the rotated value. There is no error return. 


Compatibility Standards: None 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 

See Also _lrotl, _lrotr 


Example /* ROT.C: This program uses _rotr and _rotl with different shift 
* values to rotate an integer. 
* / 


dEinclude <stdlib.h> 
dEinclude <stdio.h> 


void main( void ) 
if 
unsigned val = Qx@fd93; 


printf( "0x%4.4x rotated left three times is 0x%4.4x\n", 
Val, TOLL Vals 3: 2° 0% 

printf( "@x%4.4x rotated right four times is 0x%4.4x\n", 
val, _rotr( val, 4 ) ); 
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634 _rotl, _ rotr 


Output Q@xfd93 rotated left three times is @xec9f 
@xfd93 rotated right four times is @x3fd9 


Description 


Remarks 
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scanf 


Reads formatted data from the standard input stream. 
#include <stdio.h> 
int scanf( const char *format [[,argument]... ); 


format Format control 


argument Optional argument 


The scanf function reads data from the standard input stream stdin into the loca- 
tions given by argument. Each argument must be a pointer to a variable with a 
type that corresponds to a type specifier in format. The format controls the inter- 
pretation of the input fields. The format can contain one or more of the following: 


= = White-space characters: blank (’ ’); tab (\t); or newline (\n). A white-space char- 
acter causes scanf to read, but not store, all consecutive white-space characters 
in the input up to the next non-white-space character. One white-space charac- 
ter in the format matches any number (including 0) and combination of white- 
space characters in the input. 


= Non-white-space characters, except for the percent sign (% ). A non-white- 
space character causes scanf to read, but not store, a matching non-white- 
space character. If the next character in stdin does not match, scanf terminates. 


= Format specifications, introduced by the percent sign (% ). A format specifica- 
tion causes scanf to read and convert characters in the input into values of a 
specified type. The value is assigned to an argument in the argument list. 


The format is read from left to right. Characters outside format specifications are 
expected to match the sequence of characters in stdin; the matching characters in 
stdin are scanned but not stored. If a character in stdin conflicts with the format 

specification, scanf terminates. The character is left in stdin as if it had not been 

read. 


When the first format specification is encountered, the value of the first input 
field is converted according to this specification and stored in the location that is 
specified by the first argument. The second format specification causes the second 
input field to be converted and stored in the second argument, and so on through 
the end of the format string. 
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scanf 


An input field is defined as all characters up to the first white-space character 
(space, tab, or newline), or up to the first character that cannot be converted ac- 
cording to the format specification, or until the field width (if specified) is 
reached. If there are too many arguments for the given specifications, the extra 
arguments are evaluated but ignored. The results are unpredictable if there are not 
enough arguments for the format specification. 


A format specification has the following form: 


Zo(L*]] [width] {FI N}T th! 1} lepe 


Each field of the format specification is a single character or a number signifying a 
particular format option. The type character, which appears after the last optional 
format field, determines whether the input field is interpreted as a character, a 
string, or a number. The simplest format specification contains only the percent 
sign and a type character (for example, %s). 


Each field of the format specification is discussed in detail below. If a percent sign 
(%) is followed by a character that has no meaning as a format-control character, 
that character and the following characters (up to the next percent sign) are treated 
as an ordinary sequence of characters—that is, a sequence of characters that must 
match the input. For example, to specify that a percent-sign character is to be 
input, use %%. 


An asterisk (*) following the percent sign suppresses assignment of the next input 
field, which is interpreted as a field of the specified type. The field is scanned but 
not stored. 


The width is a positive decimal integer controlling the maximum number of char- 
acters to be read from stdin. No more than width characters are converted and 
stored at the corresponding argument. Fewer than width characters may be read if 
a white-space character (space, tab, or newline) or a character that cannot be con- 
verted according to the given format occurs before width is reached. 


The optional F and N prefixes allow the user to specify whether the argument is 
far or near, respectively. F should be prefixed to an argument pointing to a far 
object, while N should be prefixed to an argument pointing to a near object. Note 
also that the F and N prefixes are not part of the ANSI definition for scanf, but are 
instead Microsoft extensions, which should not be used when ANSI portability is 
desired. 


The optional prefix | indicates that the long version of the following type is to be 
used, while the prefix h indicates that the short version is to be used. The corre- 
sponding argument should point to a long or double object (with the | character) 
or a short object (with the h character). The 1 and h modifiers can be used with the 
d, i, n, 0, x, and u type characters. The 1 modifier can also be used with the e, f, 
and g type characters. The | and h modifiers are ignored if specified for any 

other type. 
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For scanf, N and F refer to the “distance” to the object being read in (near or far) 
and h and | refer to the “size” of the object being read in (16-bit short or 32-bit 
long). The list below clarifies this use of N, F, 1, and h: 


Program Code Action 


scanf( "%Ns", &x ); Read a string into near memory 
scanf( "%Fs", &x ); Read a string into far memory 
scanf( "%Nd", &x ) 

scanf( "%Fd", &x ) 
scanf( "%Nid", &x 
scanf( "%Fld", &x 


) 
) 
scanf( "%Nhp", &x ); Read a 16-bit pointer into near memory 
) 
) 
) 


Read an int into near memory 
Read an int into far memory 
; Read a long int into near memory 
Read a long int into far memory 


scanf( "%Nlp", &x 
scanf( "%Fhp", &x 
scanf( "%Flp", &x 


Read a 32-bit pointer into near memory 
Read a 16-bit pointer into far memory 
: Read a 32-bit pointer into far memory 


The type characters and their meanings are described in Table R.5. 


To read strings not delimited by space characters, a set of characters in brackets 

([ ]) can be substituted for the s (string) type character. The corresponding input 
field is read up to the first character that does not appear in the bracketed character 
set. If the first character in the set is a caret (‘), the effect is reversed: the input 
field is read up to the first character that does appear in the rest of the character set. 


Note that %[a-z] and %[z-a] are interpreted as equivalent to %[abcde...z]. This is 
a common scanf extension, but note that it is not required by the ANSI standard. 


To store a string without storing a terminating null character (’\0’), use the specifi- 
cation Yonc, where n is a decimal integer. In this case, the ¢ type character indi- 
cates that the argument is a pointer to a character array. The next n characters are 
read from the input stream into the specified location, and no null character (’\0’) 
is appended. If n is not specified, the default value for it is 1. 


The scanf function scans each input field, character by character. It may stop read- 
ing a particular input field before it reaches a space character for a variety of rea- 
sons: the specified width has been reached; the next character cannot be converted 
as specified; the next character conflicts with a character in the control string that 
it is Supposed to match; or the next character fails to appear in a given character 
set. For whatever reason, when scanf stops reading an input field, the next input 
field is considered to begin at the first unread character. The conflicting character, 
if there is one, is considered unread and is the first character of the next input field 
or the first character in subsequent read operations on stdin. 
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Return Value 


Table R.S Type Characters for scanf 


Character Type of Input Expected 


d 
0 
x 


hat @ 


2 C= 
eo 


g,G 


Decimal integer 

Octal integer 

Hexadecimal integer! 
Decimal, hexadecimal, or octal 
integer 

Unsigned decimal integer 
Unsigned decimal integer 


Floating-point value consisting of 
an optional sign (+ or —), a series of 
one or more decimal digits 
containing a decimal point, and an 
optional exponent (“‘e” or “E’”) 
followed by an optionally signed 
integer value. 


Character. White-space characters 
that are ordinarily skipped are read 
when C is specified; to read the 
next non-white-space character, 
use 41s. 


String 


No input read from stream or 
buffer. 


Value in the form xxxx:yyyy, where 
the digits x and y are uppercase 
hexadecimal digits. 


Type of Argument 


Pointer to int 
Pointer to int 
Pointer to int 
Pointer to int 


Pointer to unsigned int 
Pointer to unsigned long 
Pointer to float 


Pointer to char 


Pointer to character array large 
enough for input field plus a 
terminating null character (’\0’), 
which is automatically appended. 


Pointer to int, into which is stored 
the number of characters 
successfully read from the stream 
or buffer up to that point in the 
current call to scanf. 


Pointer to far pointer to void 


' Since the input for a %x format specifier is always interpreted as a hexadecimal number, the input should 
not include a leading Ox. (If Ox is included, the 0 is interpreted as a hexadecimal input value.) 


The scanf function returns the number of fields that were successfully converted 
and assigned. The return value may be less than the number requested in the call to 
scanf. The return value does not include fields that were read but not assigned. 


The return value is EOF if the end-of-file or end-of-string is encountered in the 
first attempt to read a character. 


Compatibility 


See Also 


Example 


Output 


scanf 


Standards: ANSI, UNIX 
16-Bit: DOS, QWIN 
32-Bit: DOS32X 


fscanf, printf, sscanf, vfprintf, vprintf, vsprintf 


/* SCANF.C: This program receives formatted input using scanf. */ 
#include <stdio.h> 


void main( void ) 


{ 

int 1s 

float fp; 

char c, s[8l1]; 

int result; 

printf( “Enter an integer, a floating-point number, " 

"a character and a string:\n" ); 

result = scanf( "%d “4f %c %s", &i, &fp, &c, Ss ); 

printf( “\nThe number of fields input is %d\n", result ); 

printf( "The contents are: 4d %f %c %s\n", i, fp, c, Ss );3 
} 


Enter an integer, a floating-point number, a character and a string: 
gl 

98.6 

h 

White space stops input 


The number of fields input is 4 
The contents are: 71 98.599998 h White 
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Description 


Remarks 


Return Value 


Compatibility 


See Also 


_ scrolitextwindow 


Scrolls a text window. 


#include <graph.h> 


void __ far _scrolltextwindow( short lines ); 


lines Number of lines to scroll 


The _ scrolitextwindow function scrolls a text window (previously defined by the 
_settextwindow function). The /ines argument specifies the number of lines to 
scroll. A positive value of lines scrolls the window up (the usual direction); a nega- 
tive value scrolls the window down. Specifying a number larger than the height of 
the current text window is equivalent to calling _ clearscreen(_GWINDOW ). A 
value of 0 for lines has no effect on the text. 


None. 


Standards: None 
16-Bit: DOS 
32-Bit: None 


_gettextposition, _outmem, _ outtext, _settextposition, _settextwindow 
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Example /* SCRIXWIN.C: This program displays text in text windows and then 
* scrolls, inserts, and deletes lines. 
* / 


dFinclude <stdio.h> 
dEinclude <conio.h> 
#Finclude <graph.h> 


void deleteline( void ); 
void insertline( void ); 
void status( char *msg ); 


void main( void ) 
{ 
Short row; 
char buf[40]; 


/* Set up screen for scrolling, a' { put text window around scroll area. */ 
_settextrows( 25 ); 
_clearscreen( _GCLEARSCREEN ); 


for( row = 1; row <= 25; rowt+ ) 


{ 
_settextposition( row, 1 ); 
sprintet Duty “Line Zc 22d", row + 'A' - 1, row ); 
_outtext( buf ); 

I 

_getch(); 


_settextwindow( 1, 1, 25, 10 ); 


/* Delete some lines. */ 

=-Setrextposition( tls 1.) 

for( row = 12; row < 20; rowt+ ) 
deleteline(); 

status( "Deleted 8 lines" ); 


/* Insert some lines. */ 

_settextposition( 5, 1 ); 

for( row = 1; row < 63; rowt+ ) 
insertline(); 

status( "Inserted 5 lines" ); 


/* Scroll up and down. */ 
_scrolltextwindow( -7 ); 

status( "Scrolled down 7 lines" ); 
_scrolltextwindow( 5 ); 

status( "Scrolled up 5 lines" ); 
_setvideomode( _DEFAULTMODE ); 
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/* Delete lines by scrolling them off the top of the current text window. 
* Save and restore original window. 
a / 
void deleteline() 
{ 
Short left, top, right, bottom; 
struct _rccoord rc; 


_gettextwindow( &top, &left, &bottom, &right ); 
rc = _gettextposition(); 
_settextwindow( rc.row, left, bottom, right ); 
_scrolltextwindow( _GSCROLLUP ); 
_settextwindow( top, left, bottom, right ); 
_settextposition( rc.row, rc.col ); 

"} 


/* Insert some lines by scrolling in blank lines from the top of the 
* Current text window. Save and restore original window. 
« / 
void insertline() 
{ 
short left, top, right, bottom; 
struct _rccoord rc; 


_gettextwindow( &top, &left, &bottom, &right ); 
re = _gettextposition(); 

_settextwindow( rc.row, left, bottom, right ); 
_scrolltextwindow( _GSCROLLDOWN ); 
_settextwindow( top, left, bottom, right ); 
_settextposition( rc.row, rc.col ); 


} 


/* Display and clear status in its own window. */ 
void status( char *msg ) 
{ 

short left, top, right, bottom; 

struct _rccoord rc; 


_gettextwindow( &top, &left, &bottom, &right ); 
_settextwindow( 1, 50, 2, 80 ); 
_outtext( msg ); 
_getch(); 
_clearscreen( _GWINDOW ); 
_settextwindow( top, left, bottom, right ); 
} 
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_ searchenv 


Description Searches for a file using environment paths. 
#include <stdlib.h> 


void _searchenv( char “filename, char *varname, char *pathname ); 


filename Name of file to search for 
varname Environment to search 
pathname Buffer to store complete path 
Remarks The _searchenv routine searches for the target file in the specified domain. The 


varname variable can be any environment variable that specifies a list of directory 
paths, such as PATH, LIB, INCLUDE, or other user-defined variables. The 
_searchenv function is case-sensitive, so the varname variable should match the 
case of the environment variable. 


The routine first searches for the file in the current working directory. If it doesn’t 
find the file, it next looks through the directories specified by the environment 
variable. 


If the target file is found in one of the directories, the newly created path is copied 
into the buffer pointed to by pathname. You must ensure that there is sufficient 
space for the constructed path name. If the filename file is not found, pathname 
will contain an empty null-terminated string. 


Return Value The _searchenv function does not return a value. 
Compatibility Standards: None 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 


See Also setenv, _ putenv 
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Example /* SEARCHEN.C: This program searches for a file in a directory 
* specified by an environment variable. 
* / 


d#FHinclude <stdlib.h> 
d#Ainclude <stdio.h> 


void main( void ) 


i 
char pathbuffer[_MAX_ PATH]; 
char searchfile[] = "CL.EXE"; 
char envvar[L] = "PATH"; 
/* Search for file in PATH environment variable: */ 
_searchenv( searchfile, envvar, pathbuffer ); 
if( *pathbuffer != '\@' ) 
printf( "Path for 4s: %s\n", searchfile, pathbuffer ); 
else 
printf( "%s not found\n", searchfile ); 
} 


Output Path for CL.EXE: C:\BIN\CL.EXE 


Description 


Remarks 


Return Value 


Compatibility 


See Also 


Example 


_ segread 


_ segread 


Gets the current values of segment registers. 
#include <dos.h> 
void _segread( struct _SREGS “segregs ); 


segregs Segment-register values 


The _segread function fills the structure pointed to by segregs with the current 
contents of the segment registers. The _SREGS union is described in the refer- 
ence section for _int86x. This function is intended to be used with the _intdosx 
and _int86x functions to retrieve segment-register values for later use. 


None. 


Standards: None 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: None 


_FP_SKEG, _ intdosx, _ int86x 


/* SEGREAD.C: This program gets the current segment values with _segread. */ 


d4Ainclude <dos.h> 
dAinclude <stdio.h> 


void main( void ) 


{ 


struct _SREGS segregs; 
unsigned cs, ds, es, SS; 


/* Read the segment register values */ 


CS 
ds 
es 
SS 


segread( &segregs ); 


segregs.cs; 
segregs.ds; 
segregs.es; 
segregs.ss; 


printf( "CS = 0x%.4x DS = @x%.4x ES = Q0x%.4x SS = @x%.4x\n", 


eS;. dss. 65.4, SS.) 
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Output CS = 0x0047 DS = 0x0067 ES = 0x006/7 SS 


0x0067 


CS @x2bcc DS @x2ce8 ES @x2ba3 SS @x2ce8 


ul 
il 
il 
ll 


Description 


Remarks 
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_ selectpalette 


Selects a graphics palette for CGA. 
#include <graph.h> 
short __ far _selectpalette( short number ); 


number Palette number 


The _selectpalette function works only under the video modes 
_MRES4COLOR, _MRESNOCOLOR, and _ORESCOLOR. A CGA palette 
consists of a selectable background color (Color 0) and three set colors. Under the 
_MRES4COLOR mode, the number argument selects one of the four predefined 
palettes shown in Table R.6. 


Table R.6 —~MRES4COLOR Palette Colors 


Color Index 


Palette Number Color 1 Color 2 Color 3 

0 Green Red Brown 

| Cyan Magenta White 

2 Light green Light red Yellow 

3 Light cyan Light magenta Bright white 


The _MRESNOCOLOR video mode is used with black-and-white displays, pro- 
ducing palettes consisting of various shades of gray. It will also produce color 
when used with a color display. The number of palettes available depends upon 
whether a CGA or EGA hardware package is employed. Under a CGA configura- 
tion, only the palettes shown in Table R.7 are available. Note that although four 
palette numbers are listed, palettes 0 and 1 are identical, as are palettes 2 and 3. 
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Table R.7 _~MRESNOCOLOR Mode CGA Palette Colors 


Color Index 


Palette Number Color 1 Color 2 Color 3 

0 Blue Red White 

| Blue Red White 

2 Light blue Light red Bright white 
3 Light blue Light red Bright white 


Under the EGA configuration, the three palettes shown in Table R.8 are available 
in the _MRESNOCOLOR video mode. Note that although four palette numbers 
are listed, palettes 1 and 3 are identical. 


Table R.8. ~MRESNOCOLOR Mode EGA Palette Colors 


Color Index 


Palette Number Color 1 Color 2 Color 3 
0 Green Red Brown 
I Cyan Magenta White 

2 Light green Light red Yellow 
3 Cyan Magenta White 


You can use the ORESCOLOR high resolution video mode for the Olivetti 
graphics adapters found in most Olivetti computers and in the AT&T 6300 series 
computers. In_ORESCOLOR mode, an argument number in the range 0-15 
selects one of the colors listed in Table R.9. The background color is always black 
in this mode. 


Table R.9 ~OQRESCOLOR Mode Colors 


Index Color Index Color 

0 Black 8 Dark Grey 

1 Blue 9 Light Blue 

2 Green 10 Light Green 

3 Cyan 11 Light Cyan 

4 Red 12 Light Red 

5 Magenta 13 Light Magenta 
6 Brown 14 Yellow 

7 White 15 Bright White 


Return Value The function returns the value of the previous palette. There is no error return. 


Compatibility 


See Also 


Example 


Standards: None 
16-Bit: DOS 
32-Bit: None 


_ selectpalette 


_getvideoconfig, _remappalette, _setbkcolor, _setvideomode 


/* SELPAL.C: This program changes the current CGA palette. */ 


#Hinclude <stdio.h> 
d#Hinclude <stdlib.h> 
#FHinclude <conio.h> 
#Hinclude <graph.h> 


long bkcolor[8] 


char *bkname [ ] 


{ _BLACK, _BLUE, _GREEN, 
RED, _MAGENTA, _BROWN, 
 V BLACK 3." BLUE s "GREEN", 

"RED", "MAGENTA", "BROWN", 


void main( void ) 


{ 


TA ese Kes 


if ( !_setvideomode( _MRES4COLOR ) ) 
{ 
printf( "No palettes available” ); 
exit( 1 ); 
} 
for( i = 0; i < 4; i++ ) /* 
i 
_selectpalette( i ); 
for( k = 0; k < 83 kt+t ) /* 
{ 
_clearscreen( _GCLEARSCREEN ); 
_setbkcolor( bkcolorLk] ); 
_settextposition( 1, 1 ); 
printf( “Background: 4s\tPalette: 4d", 
Tore. 4S 13:-4 Kae ee /* 
{ 
_setcolor( j ); 


_ellipse( _GFILLINTERIOR, 100, j * 30, 220, 80 + (j * 30) ); 


} 
_getch(); 
} 
} 
_setvideomode( _DEFAULTMODE ); 
exit( @ ); 


_CYAN, 
_WHITE }; 
"CYAN", 
“WHITE” }; 


Palette loop a / 


Background color loop */ 


bkname[k], i ); 
Foreground color loop */ 
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Description 


Remarks 


Return Value 


Compatibility 


See Also 


_ setactivepage 


Sets the active page. 
#include <graph.h> 
short __ far _setactivepage( short page ); 


page Memory page number 


For hardware and mode configurations with enough memory to support multiple 
screen pages, _setactivepage specifies the area in memory in which output is 
written. The page argument selects the current active page. The default page 
number is 0. 


Screen animation can be done by alternating the graphics pages displayed. Use the 
_setvisualpage function to display a completed graphics or text page while execut- 
ing graphics statements in another active page. 


These functions can also be used to control text output if you use the text functions 
_gettextcursor, _settextcursor, _outtext, _settextposition, _ gettextposition, 
_settextcolor, _ gettextcolor, _settextwindow, and — wrapon instead of the 
standard C-language I/O functions. 


The CGA hardware configuration has only 16K of RAM available to support mul- 
tiple video pages, and only in the text mode. The EGA and VGA configurations 
may be equipped with up to 256K of RAM for multiple video pages in graphics 
mode. 


If successful, the function returns the page number of the previous active page. If 
the function fails, it returns a negative value. 


Standards: None 
16-Bit: DOS 
32-Bit: None 


_getactivepage, _getvisualpage, _setvisualpage 


Example 


_ setactivepage 


/* PAGE.C illustrates video page functions including: 
* _getactivepage _getvisualpage _setactivepage _setvisualpage 
a / 


d#Ainclude <conio.h> 
#Hinclude <graph.h> 
dAinclude <stdlib.h> 


void main( void ) 

{ 
Short oldvpage, oldapage, page, row, col, line; 
struct _videoconfig vc; 
char buf [80]; 


_getvideoconfig( &vc ); 
if( vc.numvideopages < 4 ) 


exit( 1 ); /* Fail for monochrome */ 
Oldapage = _getactivepage(); 
oldvpage = _getvisualpage(); 


_displaycursor( _GCURSOROFF ); 


/* Draw arrows in different place on each page. */ 
for( page = 1; page < 4; paget+ ) 


{ 
_setactivepage( page ); 
_settextposition( 12, 16 * page ); 
_outtext( ">>>>>>>>""_); 

} 


while( !_kbhit() ) 
/* Cycle through pages 1 to 3 to show moving image. */ 
for( page = 1; page < 4; paget+ ) 
_setvisualpage( page ); 
_getch(); 


/* Restore original page (normally @) to restore screen. */ 
_setactivepage( oldapage ); 

_setvisualpage( oldvpage ); 

_displaycursor( _GCURSORON ); 

exit( @ ); 
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Description 


Remarks 


_ setbkcolor 


Sets the current background color. 
#include <graph.h> 
long __ far _setbkcolor( long color ); 


color Desired color 


The _setbkcolor function sets the current background color to the color value 
color. 


In a color text mode (such as _TEXTC80), _ setbkcolor accepts (and 
_getbkcolor returns) a color index. The value for the default colors is given 

in a table in the description of the _ settextcolor function. For example, 
_setbkcolor(2L) sets the background color to color index 2. The actual color 
displayed depends on the palette mapping for color index 2. The default is green 
in a color text mode. 


In a color graphics mode (such as __ERESCOLOR), _ setbkcolor accepts (and 
_getbkcolor returns) a color value. The value for the background color is given 
by the manifest constants defined in the GRAPH.H include file. For example, 
_setbkcolor(_GREEN) sets the background color in a graphics mode to green. 
These manifest constants are provided as a convenience in defining and manipulat- 
ing the most common colors. The actual range of colors is, in general, much 
greater. 


In general, whenever a color argument is long, it refers to a color value, and when- 
ever it is short, it refers to a color index. The two exceptions are _setbkcolor and 
_ getbkcolor. 


Since the background color is color index 0, the _remappalette function will 
act identically to the _setbkcolor function. Unlike _remappalette, however, 
_setbkcolor does not require an EGA or VGA environment. 


In a text mode, the _setbkcolor function does not affect anything already appear- 
ing on the display; only the subsequent output is affected. In a graphics mode, it 
immediately changes all background pixels. 
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Return Value In text modes, _setbkcolor returns the color index of the old background color. In 
graphics modes, _setbkcolor returns the old color value of color index 0. There 1s 
no error return. Use the _ grstatus function to check the status after a call to 


_ setbkcolor. 
Compatibility Standards: None 
16-Bit: DOS 
32-Bit: None 
See Also _getbkcolor, _grstatus, _remappalette, _selectpalette 


Example See the example for _ getcolor. 
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Description 


Remarks 


Return Value 


Compatibility 


See Also 


setbuf 


Controls stream buffering. 
#include <stdio.h> 
void setbuf( FILE *stream, char “buffer ); 


stream Pointer to FILE structure 
buffer User-allocated buffer 


The setbuf function allows the user to control buffering for stream. The stream 
argument must refer to an open file that has not been read or written. If the buffer 
argument is NULL, the stream is unbuffered. If not, the buffer must point to a 
character array of length BUFSIZ, where BUFSIZ is the buffer size as defined in 
STDIO.H. The user-specified buffer, instead of the default system-allocated buffer 
for the given stream, is used for I/O buffering. 


The stderr and (in DOS only) stdaux streams are unbuffered by default, but can 
be assigned buffers with setbuf. 


The setbuf function has been subsumed by the setvbuf function, which should be 
the preferred routine for new code. The setbuf function is retained for compati- 
bility with existing code. 


~ None. 


Standards: ANSI, UNIX 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 


fclose, fflush, fopen, setvbuf 
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Example /* SETBUF.C: This program first opens files named DATA1 and DATA2. 
* Then it uses setbuf to give DATA1 a user-assigned buffer 
* and to change DATA2 so that it has no buffer. 
 / 


dEinclude <stdio.h> 


void main( void ) 
{ 
char buf[BUFSIZ]; 
FILE *streaml, *stream2; 


if( ((streaml fopen( "datal", "a" )) != NULL) && 
((stream2 = fopen( "data2", "w" )) != NULL) ) 


{ 
/* “streaml" uses user-assigned buffer: */ 
setbuf( streaml, buf ); 
printf( “streaml set to user-defined buffer at: “%Fp\n", buf ); 


/* “stream2" is unbuffered * / 
setbuf( stream2, NULL ); 

printf( “stream2 buffering disabled\n" ); 
_fcloseall(); 


Output streaml set to user-defined buffer at: 0298:0DF2 
stream2 buffering disabled 
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Description 


Remarks 


Return Value 


Compatibility 


See Also 


Example 


_ Setcliprgn 


Sets the clipping region for graphics. 
#include <graph.h> 
void __ far _setcliprgn( short x/, short y/, short x2, short y2 ); 


xl, yl Upper-left corner of clip region 


XL, NZ Lower-right corner of clip region 


The _ setcliprgn function limits the display of subsequent graphics output and font 
text output to an area of the screen called the “clipping region.” The physical 
points (x/, y/) and (x2, y2) are the diagonally opposed sides of a rectangle that 
defines the clipping region. This function does not change the view coordinate 
system. Rather, it merely masks the screen. 


Note that the _setcliprgn function affects graphics and font text output only. To 
mask the screen for text output, use the _ settextwindow function. 


None. 


Standards: None 
16-Bit: DOS 
32-Bit: None 


_settextwindow, _setvieworg, _setviewport, _setwindow 


/* SCLIPRGN.C */ 


#Hinclude <stdlib.h> 
#Hinclude <conio.h> 
#Hinclude <graph.h> 
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void main( void ) 
{ 
/* Find a valid graphics mode. */ 
if( ! setvideomode( _MAXRESMODE ) ) 
exit( 1 ); 


/* Set clip region, then draw an ellipse larger than the region. */ 
_setcliprgn( 0, @, 200, 125 ); 
_ellipse( _GFILLINTERIOR, 8@, 50, 240, 190 ); 


_getch(); 
_setvideomode( _DEFAULTMODE ); 
exit( @ ); 
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Description 


Remarks 


Return Value 


Compatibility 


See Also 


_ setcolor 


Sets the current color. 
#include <graph.h> 
short __ far _setcolor( short color ); 


color Desired color index 


The _setcolor function sets the current color index to color. The color parameter 
is masked but always within range. The following graphics functions use the cur- 
rent color: _arc, _ellipse, _floodfill, _lineto, _outgtext, _ pie, _ polygon, 
_rectangle, and _setpixel. 


The _ setcolor function accepts a short value as an argument. It is a color index. 
The default color index is the highest numbered color index in the current palette. 


Note that the _setcolor function does not affect the output of the presentation- 
graphics functions. 


This function returns the previous color. If the function fails (e.g., if used in a text 
mode), it returns —1. 


Standards: None 
16-Bit: DOS 
32-Bit: None 
_arc functions, _ ellipse functions, _floodfill, _ getcolor, —lineto functions, 


_outgtext, _pie functions, _ polygon functions, _rectangle functions, 
_Selectpalette, _setpixel functions 


Example 
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/* GPIXEL.C: This program assigns different colors to randomly 
* selected pixels. 
* / 


#Finclude <conio.h> 
d#FHinclude <stdlib.h> 
#Hinclude <graph.h> 


void main( void ) 

{ 
Short xvar, yvar; 
struct _videoconfig vc; 


/* Find a valid graphics mode. */ 

if( ! setvideomode( _MAXCOLORMODE ) ) 
exit( 1 ); 

_getvideoconfig( &vc ); 


/* Draw filled ellipse to turn on certain pixels. */ 
—ellipse( _GFILLINTERIOR, vc.numxpixels / 6, vc.numypixels / 6, 
vc.numxpixels / 6 * 5, vc.numypixels / 6 * 5 ); 


/* Draw random pixels in random colors... */ 
while( !_kbhit() ) 
{ 


/* ...but only if they are already on (inside the ellipse). */ 
Xvar = rand() % vc.numxpixels; 
yvar = rand() % vc.numypixels; 
if( _getpixel( xvar, yvar ) != @ ) 
{ 
_setcolor( rand() % 16 ); 
_setpixel( xvar, yvar ); 


} 
_getch(); /* Throw away the keystroke. */ 


_setvideomode( _DEFAULTMODE ); 
exit( @ ); 
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_ setfillmask 


Description Sets the fill mask. 
#include <graph.h> 
void __ far _ setfillmask( unsigned char __ far *mask ); 


mask Mask array 


Remarks The _ setfillmask function sets the current fill mask, which determines the fill pat- 
tern. The mask is an 8-by-8 array of bits in which each bit represents a pixel. A 1 
bit sets the corresponding pixel to the current color, while a 0 bit leaves the pixel 
unchanged. The pattern is repeated over the entire fill area. 


If no fill mask 1s set (mask is NULL—the default), a solid (unpatterned) fill is 
performed using the current color. 


Return Value None. 
Compatibility Standards: None 
16-Bit: DOS 
32-Bit: None 
See Also _ellipse functions, _floodfill, _ getfillmask, _ pie functions, _ polygon func- 


tions, _rectangle functions 


Example /* GFILLMSK.C: This program illustrates _getfillmask and _setfillmask. */ 


dFinclude <conio.h> 
d#Finclude <stdlib.h> 
#Hinclude <graph.h> 


void ellipsemask( short xl, short yl, short x2, short y2, char __far *newmask ); 
unsigned char mask1[8] = { 0x43, @x23, @x/c, Oxf7, Ox8a, Ox4d, @x78, @x39 }; 
unsigned char mask2[8] = { @x18, Oxad, @xc0, 0x79, Oxf6, @xc4, @xa8, @x23 }; 
char oldmask[8]; 


void main( void ) 


{ 


} 


int loop; 


/* Find a valid graphics mode. */ 
if( !_setvideomode( _MAXRESMODE ) ) 
Axi te 1. ds 


/* Set first fill mask and draw rectangle. */ 
_setfillmask( maskl ); 

_rectangle( _GFILLINTERIOR, 20, 20, 100, 100 
_getch(); 


/* Call routine that saves and restores mask. 
ellipsemask( 60, 60, 150, 150, mask2 ); 
_getch(); 


/* Back to original mask. */ 


ys 


* / 


_ setfillmask 


_rectangle( _GFILLINTERIOR, 120, 120, 190, 190 ); 


_getch(); 


_setvideomode( _DEFAULTMODE ); 
exit( @ ); 


/* Draw an ellipse with a specified fill mask. */ 


void ellipsemask( short xl, short yl, short x2, short y2, char 


{ 


unsigned char savemask[8]; 


_getfillmask( savemask ); 
_setfillmask( newmask ); 
_ellipse( _GFILLINTERIOR, xl, yl, x2, y2 ); 
_setfillmask( savemask ); 


/* Save mask 


/* 
/* 
/* 


Set new mask 
Use new mask 
Restore original 


* / 
* / 
* / 
* / 
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Description 


Remarks 


_ setfont 


Loads a single font. 
#include <graph.h> 
short __ far _setfont( const char __ far *options ); 


options String describing font characteristics 


The _setfont function finds a single font, from the set of registered fonts, that has 
the characteristics specified by the options string. If a font is found, it is made the 

current font. The current font is used in all subsequent calls to the _ outgtext func- 
tion. There can be only one active font at any time. 


The options string is a set of characters that specifies the desired characteristics of 
the font. The _ setfont function searches the list of registered fonts for a font 
matching the specified characteristics. 


The characteristics that may be specified in the options string are shown in the list 
below. Characteristics specified in the options string are not case-sensitive or 
position-sensitive. 


Characteristic Description 

t’fontname’ Typeface. 

hx Character height, where x is the number of pixels. 

wy Character width, where y is the number of pixels. 

f Find only a fixed-space font (should not be used with the 
p characteristic). 

p Find only a proportionally spaced font (should not be used with 
the f characteristic). 

Vv Find only a vector font (should not be used with the r 
characteristic). 

r Find only a raster-mapped (bitmapped) font (should not be used 


with the v characteristic). 

Select a best fit font. 

nx Select font number x, where x 1s less than or equal to the value 
returned by the _registerfonts function. Use this option to “step 


through” an entire set of fonts or to save or restore a previously 
set font. 
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You can request as many options as desired, except with nx, which should be used 
alone. If mutually exclusive options are requested (such as the pair f/p or r/v), the 
_setfont function ignores them. There is no error detection for incompatible para- 
meters used with nx. 


Options can be separated by blanks in the options string. Any other character 1s 
ignored by _ setfont. 


The t (the typeface specification) in options is specified as a “t’” followed by 
fontname in single quotes. Choose fontname from the following list: 


Fontname Description 

Courier Fixed-width bitmapped font with serifs 

Helv Sans serif proportional bitmapped font 

Tms Rmn Proportional bitmapped font with serifs 

Script Proportional vector-mapped font of slanted characters formed 
from nearly continuous lines 

Modern Proportional vector-mapped font without serifs 

Roman Proportional vector-mapped font with serifs 


A b in the options field causes the _ setfont routine to automatically select the 
“best fit’ font that matches the other characteristics you have specified. If the b 
parameter is specified and at least one font is registered, _ setfont will always be 
able to set a font and will return O to indicate success. 


You can also specify a pixel width and height for fonts. If a nonexistent value is 
chosen for either, and the b option is specified, the _setfont function will choose 
the closest match. A smaller font size has precedence over a larger size. For ex- 
ample, if _setfont requests Helv 12 with best fit, and only Helv 10 and Helv 14 
are available, _setfont will select Helv 10. 


In selecting a font, the _ setfont routine uses the following precedence (rated from 
highest precedence to lowest): 

1. Pixel height 

2. Typeface 

3. Pixel width 


4. Fixed or proportional font 


If a nonexistent value is chosen for pixel height and width, the _ setfont function 
will apply a magnification factor to a vector-mapped font to obtain a suitable font 
size. This automatic magnification does not apply if the r (raster-mapped font) 
option is specified, or if a specific typeface is requested and no best fit (b) option 
is specified. 
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Return Value 


Compatibility 


See Also 


Example 


If you specify the nx parameter, _ setfont will ignore any other specified options 
and supply only the font number corresponding to x. 


Note that the font functions affect only the output from the font output function 
_outgtext; no other run-time output functions are affected by font usage. 


The _setfont function returns an index that is suitable for use with nx to indicate 
success or a negative value to indicate an error. An error occurs if a request for a 
specific font fails and the b option was not specified, or if fonts have not yet been 
registered. 


Standards: None 
16-Bit: DOS 
32-Bit: None 


_getfontinfo, _getgtextextent, _outgtext, _registerfonts, _ unregisterfonts 


See the example for _ outgtext. 


Description 


Remarks 


Return Value 


Compatibility 


See Also 


Example 
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_ Setgtextvector 


Changes the orientation of font text output. 
#include <graph.h> 
struct _xycoord __ far _setgtextvector( short x, short y ); 


x,y Integers specifying font rotation 


The _ setgtextvector function sets the current orientation for font text output to 
the vector specified by x and y. The current orientation is used in calls to the 
_ outgtext function. 


The values of x and y define the vector which determines the direction of rotation 
of font text on the screen. The text-rotation options are shown below: 


(x, y) Text Orientation 

(O, 0) Unchanged 

(1, 0) Horizontal text (default) 

(O, 1) Rotated 90 degrees counterclockwise 
(—1, 0) Rotated 180 degrees 

(O, —1) Rotated 270 degrees counterclockwise 


If other values are input, only the sign of the input is used. For example, (—3, 0) is 
interpreted as (—1, 0). 


The _setgtextvector function returns the previous vector in a structure of 
_xycoord type. If you pass the _ setgtextvector function the values (0, 0), the 
function returns the current vector values in the _ xycoord structure. 


Standards: None 
16-Bit: DOS 
32-Bit: None 


_getfontinfo, _ getgtextextent, _grstatus, _outgtext, _registerfonts, 
_setfont, _unregisterfonts 


See the example for _ outgtext. 


666 setjmp 


Description 


Remarks 


Return Value 


Compatibility 


See Also 


Example 


setimp 


Saves the current state of the program. 
#include <setjmp.h> 
int setjmp( jmp_ buf env ); 


env Variable in which environment is stored 


The setjmp function saves a stack environment that can be subsequently restored 
using longjmp. Used together this way, setjmp and longjmp provide a way to ex- 
ecute a “non-local goto.” They are typically used to pass execution control to error- 
handling or recovery code in a previously called routine without using the normal 
calling or return conventions. 


A call to setjmp causes the current stack environment to be saved in env. A sub- 
sequent call to longjmp restores the saved environment and returns control to the 
point just after the corresponding setjmp call. All variables (except register varia- 
bles) accessible to the routine receiving control contain the values they had when 
setjmp was called. 


Warning! Neither the setjmp nor the longjmp function is compatible with the 
C++ language. 


The setjmp function returns 0 after saving the stack environment. If setjmp re- 
turns as a result of a longjmp call, it returns the value argument of longjmp, or if 
the value argument of longjmp is 0, setjmp returns 1. There is no error return. 


Standards: ANSI, UNIX 


16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 
longjmp 


See the example for _fpreset. 


Description 


Remarks 


Return Value 


Compatibility 


See Also 


Example 
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_ setlinestyle 


Sets the line style. 
#include <graph.h> 
void __ far _setlinestyle( unsigned short mask ); 


mask Desired line-style mask 


Some graphics routines (_lineto, _ polygon, and _rectangle) draw straight lines 
on the screen. The type of line 1s controlled by the current line-style mask. 


The _ setlinestyle function selects the mask used for line drawing. The mask argu- 
ment is a 16-bit array, where each bit represents a pixel in the line being drawn. If 
a bit is 1, the corresponding pixel is set to the color of the line (the current color). 
If a bit is 0, the corresponding pixel is left unchanged. The template is repeated for 
the entire length of the line. 


The default mask is OXFFFF (a solid line). 
None. 


Standards: None 
16-Bit: DOS 
32-Bit: None 


_getlinestyle, _lineto functions, _ polygon functions, _rectangle functions 


See the example for _ getlinestyle. 


668 setiocale 


Description 


Remarks 


setlocale 


Defines the locale. 
#include <locale.h> 


char *setlocale( int category, const char *locale ); 


category | Category affected by locale 
locale Name of the locale that will control the specified 
category 


The setlocale function sets the categories specified by category to the locale 
specified by locale. The “locale” refers to the locality (country and language) for 
which certain aspects of your program can be customized. Some locale-dependent 
aspects include the formatting of dates and the display format for monetary values. 


The setlocale function is used to set or get the program’s current entire locale or 
simply portions of the locale information. The category argument specifies which 
portion of a program’s locale information will be affected. The macros used for 
the category argument are listed below: 


Category Parts of Program Affected 

LC_ALL All categories listed below. 

LC_COLLATE The strcoll and strxfrm functions. 

LC_CTYPE The character-handling functions (except for isdigit, isxdigit, 
mbstowcs, and mbtowc, which are unaffected). 

LC_MONETARY Monetary formatting information returned by the localeconv 
function. 

LC_NUMERIC Decimal point character for the formatted output routines 


(such as printf), for the data conversion routines, and for the 
nonmonetary formatting information returned by the 
localeconv function. 


LC_TIME The strftime function. 


The /ocale argument is a pointer to a string that specifies the name of the locale. If 
locale points to an empty string, the locale is the implementation-defined native en- 
vironment. A value of "C" specifies the minimal ANSI conforming environment 
for C translation. This is the only locale supported in Microsoft C version 6.0 and 
Microsoft C/C++ version 7.0. 


Return Value 


Compatibility 


See Also 
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If the locale argument is a null pointer, setlocale returns a pointer to the string as- 
sociated with the category of the program’s locale. The program’s current locale 
setting is not changed. 


If a valid locale and category are given, setlocale returns a pointer to the string 
associated with the specified category for the previous locale. If the locale or cate- 
gory is invalid, the setlocale function returns a null pointer and the program’s cur- 
rent locale settings are not changed. 


The pointer to a string returned by setlocale can be used in subsequent calls to 
restore that part of the program’s locale information, assuming that your program 
does not alter the pointer or the string. Later calls to setlocale will overwrite the 
string; you can use the _strdup function to save a specific locale string. 


Standards: ANSI 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 


localeconv, mblen, mbstowcs, mbtowce, strcoll, strftime, strxfrm, wcestombs, 
wctomb 


670 _ setmode 


Description 


Remarks 


Return Value 


_ setmode 


Sets the file translation mode. 


#include <fentl.h> 


#include <io.h> Required only for function declarations 
int _setmode ( int handle, int mode ); 


handle File handle 


mode New translation mode 


The _setmode function sets to mode the translation mode of the file given by 
handle. The mode must be one of the following manifest constants: 


Constant Meaning 


_O_ TEXT Sets text (translated) mode. Carriage-return—line-feed (CR-LF) 
combinations are translated into a single line-feed (LF) character 
on input. Line-feed characters are translated into CR-LF 
combinations on output. 

_O_ BINARY Sets binary (untranslated) mode. The above translations are 
suppressed. 


The _setmode function is typically used to modify the default translation mode 
of stdin, stdout, stderr, stdaux, and stdprn, but can be used on any file. If 
_setmode is applied to the file handle for a stream, the _ setmode function should 
be called before any input or output operations are performed on the stream. 


If successful, _ setmode returns the previous translation mode. A return value of 
—] indicates an error, and errno is set to one of the following values: 
Value Meaning 


EBADF Invalid file handle 
EINVAL Invalid mode argument (neither _O_ TEXT nor _O_ BINARY ) 


_ setmode 


Compatibility Standards: None 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 

See Also _creat, fopen, _ open 


Example /* SETMODE.C: This program uses _setmode to change stdin from text 
* mode to binary mode. 
* / 


dAinclude <stdio.h> 
dtinclude <fcntl.h> 
dFinclude <io.h> 


void main( void ) 


{ 
int result; 
/* Set "stdin" to have binary mode: */ 
result = _setmode( _fileno( stdin ), _0O BINARY ); 
if( result == -1 ) 
perror( "Cannot set mode" ); 
else 
printf( ""stdin' successfully changed to binary mode\n" ); 
i 


Output ‘stdin’ successfully changed to binary mode 
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672 _ set_new_ handler Functions 


_set_new_ handler Functions 


Description Transfer control to your error-handling mechanism if the new operator fails to 
allocate memory. 


#include <new.h> 


_PNH _set_new_handler( _PNH pNewHandler ); 
_PNH _set_nnew_handler( _PNH pNewHandler ); 
_PNH _set_fnew_handler( _ PNH pNewHandler ); 
_PNHH _set_hnew_handler( _ PNHH pNewHandler ); 
_PNHB _set_bnew_handler( _PNHB pNewHandler ); 


pNewHandler Pointer to a function that you write 


Remarks Use the C++ _set_new_ handler function to gain control if the new operator fails 
to allocate memory. The run-time system automatically calls _set_new_handler 
when new fails. 


To use _set_new_ handler, you must write an exception-handling function and 
then pass it as an argument to _set_new_ handler. To facilitate the easy declara- 
tion of this new handler, three pointer-to-function types—_PNH, _ PNHH, and 
— PNHB—are defined in NEW.H and described in the following table: 


Type Description 


_PNH Pointer to a function that returns type int and takes an argument of 
type size_t. Use size_t to specify the amount of space to be allocated. 


_PNHH Pointer to a function that returns type int and takes two arguments— 
the type unsigned long and the type size_t arguments specified to 
the huge new operator. 

_PNHB Pointer to a function that returns type int and takes two arguments— 
the type __segment and the type size_t arguments specified to the 
based new operator. Your function must ensure the correct binding of 
the segment variable to its return value. 


Basically, _set_new_handler is a garbage collection scheme. The run-time sys- 
tem retries allocation each time your function returns a nonzero value and fails 
new if your function returns 0. 
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An occurrence of one of the _set_new_ handler functions in a program registers 
the exception-handling function specified in the argument list with the run-time 
system: 


dFinclude <new.h> 


int handle_program_memory_depletion( size_t ) 


{ 
// Your code 

} 

void main( void ) 

{ 
_set_new_handler( handle_program_memory_depletion ); 
int *pi = new int[BIG_NUMBER]; 

} 


You can save the function address that was last passed to the _set_new_ handler 
function and then reinstate it at a later time: 


_PNH old_handler = _set_new_handler( my_handler ); 
// Code that requires my_handler 
_set_new_handler( old_handler ) 

// Code that requires old_handler 


The _ set_new_ handler function is defined in five different forms that allow you 
to manage the heap for five different memory models: 


Prototype Purpose 

_PNH _set_new_handler( _PNH ); Default new handler 
_PNH _set_nnew_handler( _PNH ); Manages the near heap 
_PNH _set_fnew_handler( _PNH ); Manages the far heap 
_PNHH _set_hnew_handler( __PNHH ); Manages the huge heap 
_PNHB _set_bnew_handler( _PNHB ); Manages based heaps 


The _set_new_ handler function automatically maps to either the 
_set_nnew_ handler or the _set_fnew_ handler function, depending on the de- 
fault data model. 


If the default memory model is either small or medium, you can call 
_set_fnew_ handler to manage the far heap. If the default memory model is 
either compact or large, you can call _set_nnew_handler to manage the near 
heap. 


You can explicitly call the _ set_hnew_ handler and the _ set_ bnew_ handler 
functions to manage both the huge and based heaps. 


674 _ set_new_ handler Functions 


In a multithreaded environment, handlers are maintained separately for each 
process and thread. Each new process lacks installed handlers. Each new thread 
gets a copy of its parent thread’s new handlers. Thus, each process and thread 1s in 
charge of its own free-store error handling. 


Return Value The _set_new_ handler function returns a pointer to the allocated program 
memory if successful. It returns a O if it’s unsuccessful. 
Compatibility _set_new_handler 


Standards: None 

16-Bit: DOS, WIN, WIN DLL 

32-Bit: DOS32X 

_set_bnew_handler, _set_fnew_handler, _set_hnew_ handler, 


_set_nnew_handler 


Standards: None 


16-Bit: DOS, WIN, WIN DLL 
32-Bit: None 
See Also _bfreeseg, _ bheapseg, calloc, delete, free, malloc, new, realloc 


For more information on the new and delete operators, see Chapter 5 of the C++ 
Language Reference (in the Microsoft C/C++ version 7.0 documentation set). 


Example /* HANDLER.CPP: This program uses _set_new_handler to print an 
* error message if the new operator fails. 
* / 


dtinclude <stdio.h> 
d4FAinclude <new.h> 


/* Allocate memory in chunks of size MemBlock. */ 
const size_t MemBlock = 1024; 


/* Allocate a memory block for the printf function to use in case 
* Of memory allocation failure; the printf function uses malloc. 
* The failsafe memory block must be visible globally because the 
* handle_program_memory_depletion function can take one 
* argument only. 

* / 
char * failsafe = new char[128]; 


_set_new_handler Functions 


/* Declare a customized function to handle memory-allocation failure. 
* Pass this function as an argument to _set_new_handler. 


* / 
int 


handle_program_memory_depletion( size_t ); 


void main( void ) 


{ 


int 


// Register existence of a new memory handler. 


_set_new_handler( handle_program_memory_depletion ); 


size_t *pmemdump = new size_t[MemBlock]; 
for( ; pmemdump != 0; pmemdump = new size_t[MemBlock] ); 


handle_program_memory_depletion( size_t size ) 


// Release character buffer memory. 

delete failsafe; 

printf( "Allocation failed, " ); 

printf( "Zu bytes not available.\n", size ); 
// Tell new to stop allocation attempts. 
return Q; 
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676  #_ Setpixel Functions 


Description 


Remarks 


Return Value 


Compatibility 


See Also 


_ setpixel Functions 


Set a pixel to the current color. 
#include <graph.h> 


short __ far _setpixel( short x, short y ); 


short __ far _setpixel_ w( double wx, double wy ); 


x,y Target pixel 


wx, wy Target pixel 


The _setpixel and the _setpixel_w functions set a pixel at a specified location to 
the current color. 


The _ setpixel function sets the pixel at the view-coordinate point (x, y) to the 
current color. 


The _ setpixel_ w function sets the pixel at the window-coordinate point (wx, wy) 
to the current color. 


The function returns the previous value of the target pixel. If the function fails (for 
example, the point lies outside of the clipping region), it will return —1. 


Standards: None 
16-Bit: DOS 
32-Bit: None 


_getpixel functions, —_setcolor 


Example 
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/* GPIXEL.C: This program assigns different colors to randomly 
* selected pixels. 
* / 


4FAinclude <conio.h> 
dAinclude <stdlib.h> 
#Hinclude <graph.h> 


void main( void ) 

{ 
Short xvar, yvar; 
struct _videoconfig vc; 


/* Find a valid graphics mode. */ 

if( !_setvideomode( _MAXCOLORMODE ) ) 
exit( 1 ); 

_getvideoconfig( &vc ); 


/* Draw filled ellipse to turn on certain pixels. */ 
_ellipse( _GFILLINTERIOR, vc.numxpixels / 6, vc.numypixels / 6, 
vc.numxpixels / 6 * 5, vc.numypixels / 6 * 5 ); 


/* Draw random pixels in random colors... */ 
while( !_kbhit() ) 
{ 


/* ...but only if they are already on (inside the ellipse). */ 
Xvar = rand() 4 vc.numxpixels; 
yvar = rand() % vc.numypixels; 
if( _getpixel( xvar, yvar ) != @ ) 
{ 
_setcolor( rand() % 16 ); 
_setpixel( xvar, yvar ); 


} 
_getch(); /* Throw away the keystroke. */ 


_setvideomode( _DEFAULTMODE ); 
exit( @ ); 


678 _ settextcolor 


_ settextcolor 


Description Sets the current text color. 
#include <graph.h> 
short __ far _settextcolor( short index ); 


index Desired color index 


Remarks The _ settextcolor function sets the current text color to the color index specified 
by index. The default text color is the same as the maximum color index for the 
current video mode. 


The _settextcolor routine sets the color for the _outtext and _outmem functions 
only. It does not affect the color of the printf function or the color of text output 
with the _ outgtext font routine. Use the _setcolor function to change the color of 
font output. 


In text color mode, you can specify a color index in the range 0-31. The colors in 
the range 0—15 are interpreted as normal (non-blinking). The normal color range 
is defined below: 


Index Co | Index Color 

0 Bla. . 8 Dark gray 

l Blue 9 Light blue 

Bi Green 10 Light green 

3 Cyan 1] Light cyan 

4 Red 12 Light red 

5 Magenta 13 Light magenta 
6 Brown 14 Yellow 

7 White 15 Bright white 


Blinking is selected by adding 16 to the normal color value. 


Return Value 
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In every text mode, including monochrome, _ getvideoconfig returns the value 32 
for the number of available colors. The value 32 indicates the range of values 
(0-31) accepted by the _ settextcolor function. This includes sixteen normal 
colors (O—15) and sixteen blinking colors (16-31). Monochrome text mode has 
fewer unique display attributes, so some color values are redundant. However, 
because blinking is selected in the same manner, monochrome text mode has the 
same range (O—31) as other text modes. 


The function returns the color index of the previous text color. There is no error re- 
turn. Use the _ grstatus function to check the status after a call to _settextcolor. 


Compatibility Standards: None 
16-Bit: DOS 
32-Bit: None 
See Also _gettextcolor, _grstatus, _outmem, _outtext 


Example 


/* QUTTXT.C: This example illustrates text output functions: 


** _gettextcolor _getbkcolor -_gettextposition _outtext 
* _settextcolor  _setbkcolor _settextposition 
* / 


dFinclude <conio.h> 
d#Finclude <stdio.h> 
#Hinclude <graph.h> 


char buffer [8]; 


void main( void ) 


{ 


/* Save original foreground, background, and text position */ 
short blink, fgd, oldfgd; 

long bgd, oldbgd; 

struct _rccoord oldpos; 


/* Save original foreground, background, and text position. */ 
oldfgd = _gettextcolor(); 

oldbgd = _getbkcolor(); 

oldpos = _gettextposition(); 

_clearscreen( _GCLEARSCREEN ); 
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/* First time no blink, second time blinking. */ 
for( blink = @; blink <= 16; blink += 16 ) 


{ 
/* Loop through 8 background colors. */ 
for( bgd = @; bgd < 8; bgdt++ ) 
{ 
_setbkcolor( bgd ); 
_settextposition( (short)bgd + ((blink / 16) * 9) + 3, 1 ); 
_settextcolor( 7 ); 
sprintf(buffer, "Back: %d Fore:", bgd ); 
_outtext( buffer ); 
/* Loop through 16 foreground colors. */ 
for( fgd = @; fgd < 16; fgd++ ) 
[ 
_settextcolor( fgd + blink ); 
sprintf( buffer, " %2d ", fgd + blink ); 
_outtext( buffer ); 
} 
} 
} 
_getch(); 


/* Restore original foreground, background, and text position. */ 
_settextcolor( oldfgd ); 

_setbkcolor( oldbgd ); 

_clearscreen( _GCLEARSCREEN ); 

_settextposition( oldpos.row, oldpos.col ); 

exit( @ ); 
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_ settextcursor 


Description Sets the current cursor attribute. 
#include <graph.h> 
short __ far _settextcursor( short attr ); 


attr Cursor attribute 


Remarks The _ settextcursor function sets the cursor attribute (1.e., the shape) to the value 
specified by attr. The high-order byte of attr determines the top line of the cursor 
within the character cell. The low-order byte of attr determines the bottom line of 
the cursor. 


The _ settextcursor function uses the same format as the BIOS routines in setting 
the cursor. Typical values for the cursor attribute are listed below: 


Attribute Cursor Shape 
0x0707 Underline 
0x0007 Full block cursor 
0x0607 Double underline 
Ox2000 No cursor 


Note that this function works only in text video modes. 


Return Value The function returns the previous cursor attribute, or —1 if an error occurs (such as 
calling the function in a graphics screen mode). 


Compatibility Standards: None 
16-Bit: DOS 
32-Bit: None 


See Also _displaycursor, _ gettextcursor 
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Example /* DISCURS.C: This program changes the cursor shape using _gettextcursor 
* and _settextcursor, and hides the cursor using _displaycursor. 
« / 


dAinclude <conio.h> 
#Hinclude <graph.h> 


void main( void ) 
{ 
short oldcursor; 
short newcursor = @x0@Q7; /* Full block cursor */ 


/* Save old cursor shape and make sure cursor is on. */ 
oldcursor = _gettextcursor(); 

_clearscreen( _GCLEARSCREEN ); 

_displaycursor( _GCURSORON ); 


_outtext( "\nOld cursor shape: " ); 
_getch(); 

/* Change cursor shape. */ 
_outtext( "\nNew cursor shape: " ); 
_settextcursor( newcursor ); 
_getch(); 


/* Restore original cursor shape. */ 
_outtext( "\n" ); 
_settextcursor( oldcursor ); 


Description 


Remarks 


Return Value 
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_ Settextposition 


Sets the text position. 
#include <graph.h> 
struct _rccoord __ far _settextposition( short row, short column ); 


row, column New output start position 


The _settextposition function sets the current text position to the display point 
(row, column). The _outtext and _outmem functions (and standard console I/O 
routines, such as printf) output text at that point. Note that _ settextposition does 
not affect the text position for the _ outgtext function; use the _moveto function 
instead. 


The _recoord structure, defined in GRAPH.H, contains the following elements: 


Element Description 
short row Row coordinate 
short col Column coordinate 


The function returns the previous text position in an _recoord structure, defined 


in GRAPH.H. 
Compatibility Standards: None 

16-Bit: DOS 

32-Bit: None 


See Also 


Example 


_gettextposition, _moveto, _outmem, _outtext, _settextwindow 


/* OUTTXT.C: This example illustrates text output functions: 


* _gettextcolor _getbkcolor -_gettextposition -_outtext 
* _settextcolor _setbkcolor -_settextposition 
* / 


dEinclude <conio.h> 
d4einclude <stdio.h> 
#Hinclude <graph.h> 


char buffer [80]; 
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void main( void ) 
{ 
/* Save original foreground, background, and text position */ 
Short blink, fgd, oldfgd; 
long bgd, oldbgd; 
struct _rccoord oldpos; 


/* Save original foreground, background, and text position. */ 
oldfgd = _gettextcolor(); 

oldbgd = _getbkcolor(); 

oldpos = _gettextposition(); 

_clearscreen( _GCLEARSCREEN ); 


/* First time no blink, second time blinking. */ 
for( blink = 0; blink <= 16; blink += 16 ) 


{ 
/* Loop through 8 background colors. */ 
for( bgd = @; bgd < 8; bgd++ ) 
i 
_setbkcolor( bgd ); 
_settextposition( (short)bgd + ((blink / 16) * 9) + 3, 1 ); 
_settextcolor( 7 ); 
sprintf(buffer, "Back: %d Fore:", bgd ); 
_outtext( buffer ); 
/* Loop through 16 foreground colors. */ 
for( fgd = 0; fgd < 16; fgd++ ) 
{ 
_settextcolor( fgd + blink ); 
sprintf( buffer, " 42d ", fgd + blink ); 
_outtext( buffer ); 
} 
} 
} 
_getch(); 


/* Restore original foreground, background, and text position. */ 
_settextcolor( oldfgd ); 
_setbkcolor( oldbgd ); 
_clearscreen( _GCLEARSCREEN ); 
_settextposition( oldpos.row, oldpos.col ); 
} 


Description 


Remarks 


Return Value 


Compatibility 


See Also 
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_ settextrows 


Sets the number of screen rows for text modes. 
#include <graph.h> 
short __ far _settextrows( short rows ); 


rows Number of text rows 


The _ settextrows function specifies the number of screen rows to be used in text 
modes. 


If the constant_MAXTEXTROWS is specified for the rows argument, the 
_settextrows function will choose the maximum number of rows available. In text 
modes, this is 50 rows on VGA, 43 on EGA, and 25 on others. In graphics modes 
that support 30 or 60 rows, _MAXTEXTROWS specifies 60 rows. In SVGA 
modes, MAXTEXTROWS specifies the vertical resolution (as returned in a 

_ videoconfig struct by the _ getvideoconfig function) divided by 8. 


This function returns the numbers of rows set. The function returns O if an error 
occurred. 


Standards: None 
16-Bit: DOS 
32-Bit: None 


_getvideoconfig, _outtext, _setvideomode, _setvideomoderows 
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Example /* STXTROWS.C: This program attempts to set the screen height. It returns 
* an errorlevel code of 1 (fail) or @ (success) that could be tested in 
* a batch file. 
* / 


ftinclude <graph.h> 
fHinclude <stdlib.h> 


void main( int argc, char **argv ) 
{ 
Short rows; 


if( !(rows = atoi( argv[i] )) ) 


_outtext( "\nSyntax: STXTROWS [ 25 | 43 | 5@ J\n" ); 
exit( 1 ); 
} 
/* Make sure new rows are the same as requested rows. */ 
if( _settextrows( rows ) != rows ) 
{ 
_outtext( "\nInvalid rows\n" ); 
exit( 1 ); 
} 
else 
exit( @ ); 
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_ settextwindow 
Description Creates a text window. 
#include <graph.h> 


void __ far _settextwindow( short r/, short c/, short r2, short c2 ); 


rl,cl Upper-left corner of window 
r2, c2 Lower-right corner of window 
Remarks The _settextwindow function specifies a window in row and column coordinates 


where the text output to the screen by the _ outtext or _outmem function is dis- 
played. The arguments (r/, c/) specify the upper-left corner of the text window, 
and the arguments (r2, c2) specify the lower-right corner of the text window. 


Text is output from the top of the text window down. When the text window is 
full, the uppermost line scrolls up out of it. 


Note that this function does not affect the output of presentation-graphics text 
(e.g., labels, axis marks, etc.), the output of the font display routine _ outgtext, or 
the output of the standard I/O routine printf. Use the _ setviewport function to 
control the display area for presentation graphics or fonts. 


Return Value None. Use the _ grstatus function to check conditions of success or failure. 
Compatibility Standards: None 

16-Bit: DOS 

32-Bit: None 
See Also _gettextposition, _ gettextwindow, _grstatus, _outmem, _outtext, 


_scrolitextwindow, _settextposition 


Example See the example for _ scrolltextwindow. 
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Description 


Remarks 


Return Value 


setvbuf 


Controls stream buffering and buffer size. 
#include <stdio.h> 


int setvbuf( FILE *stream, char *buffer, int mode, size_t size ); 


stream Pointer to FILE structure 

buffer User-allocated buffer 

mode Mode of buffering: _[OFBF (full buffering), 
_IOLBF (line buffering), _lONBF (no buffer) 

size Size of buffer 


The setvbuf function allows the program to control both buffering and buffer size 
for stream. The stream must refer to an open file that has not been read from or 
written to since it was opened. The array pointed to by buffer is used as the buffer, 
unless it is NULL, and an automatically allocated buffer size bytes long is used. 


The mode must be _IOFBF, _IOLBF, or _IONBF. If mode is _TOFBF or 
_IOLBF, then size is used as the size of the buffer. If mode is _IONBF, the 
stream is unbuffered and size and buffer are ignored. 


Values for mode and their meanings are: 


Type Meaning 


_IOFBF Full buffering; that is, buffer is used as the buffer and size is used 
as the size of the buffer. If buffer is NULL, an automatically 
allocated buffer size bytes long is used. 


_IOLBF With DOS, the same as _IOFBF. 
_IONBF No buffer is used, regardless of buffer or size. 


The legal values for size are greater than O and less than 32,768. 


The return value for setvbuf is 0 if successful, and a nonzero value if an illegal 
type or buffer size 1s specified. 


Compatibility Standards: ANSI, UNIX 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 
See Also fclose, fflush, fopen, setbuf 
Example /* SETVBUF.C: This program opens two streams named streaml and stream2. 


setvbuf 


* It then uses setvbuf to give streaml a user-defined buffer of 1024 
* bytes and stream2 no buffer. 


* / 
#Finclude <stdio.h> 


void main( void ) 


{ 
char buf[1024]; 
FILE *streaml, *stream2; 
if( ((streaml = 
((stream2 = 
{ 
if( setvbuf( streaml, 
printf ( “Incorrect 
else 
printf( “"streaml' 
if( setvbuf( stream2, 
printf( “Incorrect 
else 
printf ( “"stream2' 
_fcloseall(); 
} 
} 


Output 


fopen( "datal", "a" )) != NULL) && 
fopen( "data2", "w" )) != NULL) ) 


buf, _IOFBF, sizeof( buf ) ) !=@ ) 
type or size of buffer for streaml\n" ); 


now has a buffer of 1024 bytes\n" ); 
NULL, _IONBF, @ ) != @ ) 
type or size of buffer for stream2\n" ); 


now has no buffer\n" ); 


"streaml' now has a buffer of 1024 bytes 
"stream2' now has no buffer 


689 


690 _ setvideomode 


_ setvideomode 


Description Sets the video mode. 
#include <graph.h> 
short __ far _setvideomode( short mode ); 


mode Desired mode 


Remarks The _ setvideomode function selects a screen mode appropriate for a particular 
hardware/display configuration. The mode argument can be one of the manifest 
constants shown in Tables R.10 and R.11 and defined in GRAPH.H. Table R.10 
describes only standard hardware; however, display hardware that is strictly com- 
patible with IBM, Hercules, or Olivetti hardware should also work as described. 


Table R.10 Manifest Constants for Screen Mode 


Mode Type! Size2 Colors3 Adapter+ 
_DEFAULTMODE Mode existing at 

startup 
_MAXRESMODE Highest resolution 


in graphics mode 
_~MAXCOLORMODE = Maximum colors 
in graphics mode 


_TEXTBW40 BW/T 40 columns a7 CGA 
_TEXTC40 C/T 40 columns 32 CGA 
_TEXTBWS80 BW/T 80 columns 32 CGA 
_TEXTC80 C/T 80 columns 32 CGA 
_MRES4COLOR C/G 320 x 200 4 CGA 
_MRESNOCOLOR BW/G 320 x 200 4 CGA 
_HRESBW BW/G 640 x 200 2 CGA 
_TEXTMONO M/T 80 columns 32 MDPA 
_HERCMONOS M/G/Hercules 720 x 348 2 HGC 
graphics 
_MRES16COLOR C/G 320 x 200 16 EGA 
—_HRES16COLOR C/G 640 x 200 16 EGA 
_ERESNOCOLOR M/G 640 x 350 4 EGA 


—_ERESCOLOR C/G : 640 x 350 16/4 EGA 


Table R.10 (continued) 


Mode 


_VRES2COLOR 
—VRES16COLOR 
_MRES256COLOR 
—ORESCOLOR 


| M indicates monochrome, BW indicates monochrome, C indicates color output, T indicates text, and G 
indicates graphics generation. 


Type! 
C/G 
C/G 
C/G 
C/G 
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Size2 

640 x 480 
640 x 480 
320 x 200 
640 x 400 


Colors} 


2 

16 

256 

1 of 16 
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Adapter+ 
VGA 
VGA 
VGA 
OGA 


For text modes, size is given in characters (number of columns). For graphics modes, size is given in pixels 


(horizontal x vertical). 


> For monochrome displays, the number of colors is the number of attributes or shades of gray. 


‘ Adapters are the IBM (and compatible) Monochrome Adapter (MDPA), Color Graphics Adapter (CGA), 
Enhanced Graphics Adapter (EGA), Video Graphics Array (VGA), Hercules-compatible adapter (HGC), 


and Olivetti-compatible adapter (OGA). 


> In _HERCMONO mode, the text dimensions are 80 columns by 25 rows, with a9 by 14 character box. 
The bottom two scan lines of row 25 are not visible. 


Table R.11 lists the manifest constants that support the Super VGA screen modes 

specified by the Video Electronic Standards Association (VESA). Other nonstand- 
ard Super VGA modes may also be supported. Note that some, or all, of these 
manifest constants may be supported by graphics cards that support the VESA 
Super Video standard VS891001. Other modes may also be supported; a TSR 
driver may be required. For more details on these constants, see Chapter 9 of Pro- 
gramming Techniques (in the Microsoft C/C++ version 7.0 documentation set). 


Table R.11 VESA Manifest Constants for Screen Mode 


Mode 


—ORES256COLOR 
—VRES256COLOR 
_SRES16COLOR2 
_SRES256COLOR2 
_XRES16COLOR? 
_ XRES256COLOR3 
_ZRES16COLOR‘4 
_ZRES256COLOR4 


VESA No. 


Ox0100 
Ox0101 
Ox0102 
Ox0103 
Ox0104 
0Ox0105 
Ox0106 
Ox0107 


Type! 


C/G 
C/G 
C/G 
C/G 
C/G 
C/G 
C/G 
C/G 


Size 

640 x 400 
640 x 480 
800 x 600 
800 x 600 
1024 x 768 
1024 x 768 
1280 x 1024 
1280 x 1024 


' C indicates color output and G indicates graphics generation. 


Requires NEC MultiSync 3D or equivalent or better. 


: Requires NEC MultiSync 4D or equivalent or better. 


‘ Requires NEC MultiSync 5D or equivalent or better. 


Colors 


256 
256 
16 
256 
16 
256 
16 
256 


Adapter 


SVGA 
SVGA 
SVGA 
SVGA 
SVGA 
SVGA 
SVGA 
SVGA 
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Warning! Do not attempt to set_SRES16COLOR, _SRES256COLOR, 
_XRES16COLOR, _ XRES256COLOR, _ ZRES16COLOR, or 
_ZRES256COLOR without ensuring that your monitor can safely handle that 
resolution. Otherwise, you may risk damaging your display monitor! Consult your 
owner’s manual for details. 


_MAXRESMODE and _MAXCOLORMODE 

The two special modes __MAXRESMODE and _MAXCOLORMODE select 
the highest resolution or greatest number of colors available with the current hard- 
ware, respectively. These two modes fail for adapters that do not support graphics 
modes. They never select _SRES, _ XRES, or _ ZRES mode. 


Table R.12 lists the video mode selected for different adapter and monitor combi- 
nations when _MAXRESMODE or _MAXCOLORMODE is specified: 


Table R.12 Modes Selected by _MAXRESMODE and _MAXCOLORMODE 


Adapter/Monitor _MAXRESMODE _MAXCOLORMODE 
MDPA fails fails 

HGC _HERCMONO _HERCMONO 
CGA color! _HRESBW _MRES4COLOR 
CGA noncolor! _HRESBW _MRESNOCOLOR 
OCGA —~ORESCOLOR _MRES4COLOR 
OEGA color _ORESCOLOR _ERESCOLOR 
EGA color 256K _HRES16COLOR _HRES16COLOR 
EGA color 64K _HRES16COLOR _HRES16COLOR 
EGA ecd 256K _ERESCOLOR _ERESCOLOR 
EGA ecd 64K _ERESCOLOR _HRES16COLOR 
EGA mono _ERESNOCOLOR _ERESNOCOLOR 
MCGA _ VRES2COLOR _MRES256COLOR 
VGA _ VRES16COLOR _MRES256COLOR 
OVGA _ VRES16COLOR _MRES256COLOR 
SVGA _ VRES256COLOR2 _ VRES256COLOR2 


' Color monitor is assumed if the startup text mode was _TEXTC80 or _TEXTC40 or if the startup mode 
was graphics mode. Composite or other noncolor CGA monitor is assumed if startup mode was 
_TEXTBWS80 or _TEXTBW40. 


* If _VRES256COLOR is supported by the adapter/monitor combination. If not, MAXCOLORMODE 
will be either __ORES256COLOR (if supported) or _MRES256COLOR and _MAXRESMODE will be 
_VRES16COLOR. | 


Return Value 
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Hercules Support 
You must install the Hercules driver MSHERC.COM before running your pro- 


gram. Type MSHERC to load the driver. This can be automated by adding a line 
to your AUTOEXEC.BAT file. 


If you have both a Hercules monochrome card and a color video card, you should 
install MSHERC.COM with the /H (/HALF) option. The /H option causes the 
driver to use one instead of two graphics pages. This prevents the two video cards 
from attempting to use the same memory. You do not need to use the /H option if 
you have only a Hercules card. See your Hercules hardware manuals for more 
details on compatibility. 


To use a mouse, you must follow special instructions for Hercules cards in 
Microsoft Mouse Programmer’s Reference Guide. (This 1s sold separately; 
it is not supplied with either Microsoft C/C++ or the mouse package.) 


The function returns the number of text rows if the function is successful. If an 
error is encountered (that is, the mode selected is not supported by the current 
hardware configuration), the function returns 0. 


Compatibility Standards: None 
16-Bit: DOS 
32-Bit: None 
See Also _getvideoconfig, _settextrows, _setvideomoderows 


Example 


/* SVIDMODE.C: This program sets a video mode from a string given on the 
* command line. 
* / 


#Hinclude <graph.h> 
d#include <stdlib.h> 
#Hinclude <string.h> 


short modes[] = { _TEXTBW40, _TEXTC40, _TEXTBW8@, 
_TEXTC8@, _MRES4COLOR, _MRESNOCOLOR, 
_HRESBW, | _TEXTMONO, —_HERCMONO, 
~MRESI6COLOR, _HRESI6COLOR, ~ERESNOCOLOR, 
_ERESCOLOR, _~VRES2COLOR, _VRES16COLOR, 
_~MRES256COLOR, ~ORESCOLOR 

ee 

char *namesL] = { "TEXTBW40", "TEXTC40", “TEXTBW8Q", 
"TEXTC8Q", "MRES4COLOR", "MRESNOCOLOR", 
"HRESBW", ~  "TEXTMONO", "HERCMONO", 
"MRESI6COLOR", "HRESI6COLOR", "ERESNOCOLOR", 
“"ERESCOLOR", "VRES2COLOR", "“VRESI6COLOR", 


"MRES256COLOR", "ORESCOLOR" 
‘a 
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void error( char *msg ); 


void main( int argc, char *argv[] ) 


{ 
short i, num = sizeof( modes ) / sizeof( short ); 
struct _videoconfig vc; 
if( arge < 2 ) 
error( "No argument given" ); 
/* If matching name found, change to corresponding mode. */ 
for( i = @; i < num; i++ ) 
{ 
if( !_ostrempi( argv[1], names[i] ) ) 
{ 
_setvideomode( modes[i] ); 
_outtext( “New mode is: " ); 
_outtext( names[i] ); 
exit( @ ); 
} 
J 
error( “Invalid mode string" ); 
} 


void error( char *msg_ ) 
f | 
_outtext( msg ); 
exit( 1 ); 
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_ Setvideomoderows 
Description Sets the video mode and number of text rows for text modes. 
#include <graph.h> 


short __ far _setvideomoderows( short mode, short rows ); 


mode Desired mode 
rows Number of text rows 
Remarks The _ setvideomoderows function selects a screen mode for a particular 


hardware/display combination. The manifest constants for the screen mode are 
given in the reference pages for _setvideomode. The _ setvideomoderows func- 
tion also specifies the number of text rows to be used in a text mode. If the 
constant_MAXTEXTROWS is specified for the rows argument, the 
_setvideomoderows function will choose the maximum number of rows availa- 
ble. In text modes, this is 50 rows on VGA, 43 on EGA, and 25 on others. In 
graphics modes that support 30 or 60 rows, _MAXTEXTROWS specifies 60 
rows. In SVGA modes, _.MAXTEXTROWS specifies the vertical resolution (as 
returned in a _ videoconfig struct by the _ getvideoconfig function) divided by 8. 


Return Value The _ setvideomoderows function returns the numbers of rows set. The function 
returns 0 if an error occurred (e.g., if the mode is not supported). 


Compatibility Standards: None 
16-Bit: DOS 
32-Bit: None 


See Also _getvideoconfig, _settextrows, _setvideomode 
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Example /* SVMROWS.C */ 


dHinclude <stdlib.h> 
d#Finclude <conio.h> 
#Hinclude <graph.h> 


void main( void ) 
{ 
struct _videoconfig config; 


/* Set 43-line graphics mode if available. */ 
if( !_setvideomoderows( _ERESCOLOR, 43 ) ) 
{ 
_outtext( "EGA or VGA required" ); 
exit( 1 ); | 
} 
_getvideoconfig( &config ); 


/* Set logical origin to center and draw a rectangle. */ 
_setlogorg( config.numxpixels / 2 - 1, config.numypixels / 2 - 1 ); 
_rectangle( _GBORDER, -80, -50, 80, 50 ); 


_getch(); 
_setvideomode( _DEFAULTMODE ); 
exit( @ ); 
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_ setvieworg 
Description Moves the view-coordinate origin to the specified physical point. 
#include <graph.h> 


Struct _xycoord __ far _setvieworg( short x, short y ); 


x,y New origin point 
Remarks The _setvieworg function moves the view-coordinate origin (0, 0) to the physical 
point (x, y). 


The _xycoord structure, defined in GRAPH.H, contains the following elements: 


Element Description 
short xcoord x coordinate 
short ycoord y coordinate 


The _setvieworg function replaces the _setlogorg function of Microsoft C 
version 5.1. 


Return Value The function returns the physical coordinates of the previous view origin in an 
_xycoord structure, defined in GRAPH.H. 


Compatibility Standards: None 
16-Bit: DOS 
32-Bit: None 
See Also _getphyscoord, _ getviewcoord, _getwindowcoord, _setcliprgn, 


_Ssetviewport 
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Example /* SVORG.C: This program sets the view origin to the center of 
* the screen, then draws a rectangle using the new origin. 
* / 


d#Ainclude <stdlib.h> 
##include <conio.h> 
#Hinclude <graph.h> 


void main( void ) 
{ 
struct _videoconfig config; 


/* Find a valid graphics mode. */ 

if( ! setvideomode( _MAXRESMODE ) ) 
exit( 1 ); 

_getvideoconfig( &config ); 


/* Set view origin to the center of the screen. */ 
_setvieworg( config.numxpixels / 2, config.numypixels / 2 ); 
_rectangle( _GBORDER, -80, -50, 80, 50 ); 


_getch(); 
_setvideomode( _DEFAULTMODE ); 
exit( @ ); 


Description 


Remarks 


Return Value 


Compatibility 


See Also 
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_ setviewport 


Creates a viewport. 
#include <graph.h> 
void __ far _setviewport( short x/, short y/, short x2, short y2 ); 


xl, yl Upper-left corner of viewport 


x2, y2 Lower-right corner of viewport 


The _setviewport function redefines the graphics viewport. The _setviewport 
function defines a clipping region in exactly the same manner as _ setcliprgn, and 
then sets the view-coordinate origin to the upper-left corner of the region. The 
physical points (x/, y/) and (x2, y2) are the diagonally opposed corners of the rec- 
tangular clipping region. Any window transformation done with the _ setwindow 
function applies only to the viewport and not to the entire screen. The default view- 
port is the entire screen. 


None. Use the _ grstatus function to check for conditions of success or failure. 


Standards: None 
16-Bit: DOS 
32-Bit: None 


_grstatus, _setcliprgn, _setvieworg, _setwindow 
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Example /* SVIEWPRT.C: This program sets a viewport and then draws a rectangle 


* around it and an ellipse in it. 
a / 


#Hinclude <conio.h> 
#Finclude <stdlib.h> 
#Hinclude <graph.h> 


void main( void ) 
{ 
/* Find a valid graphics mode. */ 


if( !_setvideomode( _MAXRESMODE ) ) 
exit( 1 ); 


_setviewport( 100, 100, 200, 200 ); 
_rectangle( _GBORDER, 0, 0, 100, 100 ); 
_ellipse( _GFILLINTERIOR, 10, 10, 90, 90 ); 


_getch(); 


_setvideomode( _DEFAULTMODE ); 
exit( @ ); 


Description 


Remarks 


Return Value 


Compatibility 


See Also 


Example 
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_ setvisualpage 


Sets the visual page. 
#include <graph.h> 
short __ far _setvisualpage( short page ); 


page Visual page number 


For hardware configurations that have enough memory to support multiple-screen 
pages, the _setvisualpage function selects the current visual page. The page argu- 
ment specifies the current visual page. The default page number is 0. 


The function returns the number of the previous visual page. If the function fails, it 
returns a negative value. 


Standards: None 
16-Bit: DOS 
32-Bit: None 


_getactivepage, _ getvisualpage, _setactivepage, _setvideomode 


See the example for _ setactivepage. 
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Description 


Remarks 


Return Value 


Compatibility 


See Also 


_ setwindow 


Defines a graphics window coordinate system. 
#include <graph.h> 


short __ far _setwindow( short finvert, double wx/, double wy/, double wx2, 
double wy2 ); 


finvert Invert flag 
wxl, wyl Upper-left corner of window 
wx2, wy2 Lower-right corner of window 


The _setwindow function defines a window viewport. The arguments (wx/, wy/) 
specify the upper-left corner of the window, and the arguments (wx2, wy2) specify 
the lower-right corner of the window. 


The finvert argument specifies the direction of the coordinates. If finvert is TRUE, 
the y axis increases from the screen bottom to the screen top (Cartesian coordi- 
nates). If finvert is FALSE, the y axis increases from the screen top to the screen 
bottom (screen coordinates). 


Any window transformation done with the _setwindow function applies only to 
the viewport and not to the entire screen. 


If wxl equals wx2 or wy/ equals wy2, the function will fail. 


Note that this function only affects output functions suffixed with _ w or _ wxy. 


The function returns a nonzero value if successful. If the function fails (e.g., if it is 
not in a graphics mode), it returns 0. 


Standards: None 
16-Bit: DOS 
32-Bit: None 


_arc functions, _ ellipse functions, _ getwindowcoord, _ lineto functions, 
_pie functions, _setviewport, functions suffixed with _ w or _wxy 


Example 


/* 


* / 


_ setwindow 


SWINDOW.C: This program illustrates translation between window, 
view, and physical coordinates. Functions used include: 
_setwindow _getwindowcoord 
_getphyscoord _getviewcoord_wxy 


d#Hinclude <conio.h> 
deinclude <stdlib.h> 
#Hinclude <graph.h> 


enum boolean { FALSE, TRUE }; 
enum display { MOVE, DRAW, ERASE }; 


void main( void ) 


{ 


struct _xycoord view, phys; 

struct _wxycoord oldwin, newwin; 

struct _videoconfig vc; 

double xunit, yunit, xinc, yinc; 

Short color, key, fintersect = FALSE, fdisplay = TRUE; 


/* Find a valid graphics mode. */ 

if( ! setvideomode( _MAXRESMODE ) ) 
exit. Ls 

_getvideoconfig( &vc ); 


/* Set a window using real numbers. */ 
_setwindow( FALSE, -125.0, -100.0, 125.0, 100.0 ); 


/* Calculate the size of one pixel in window coordinates. 
* Then get the current window coordinates and color. 


* / 
oldwin = _getwindowcoord( 1, 1 ); 
newwin = _getwindowcoord( 2, 2 ); 


xunit = xinc = newwin.wx - oldwin.wx; 
yunit = yinc = newwin.wy - oldwin.wy; 


newwin = oldwin = _getcurrentposition_w(); 
color = _getcolor(); 

while( 1 ) 

{ 


/* Set flag according to whether current pixel is on, then 
* turn pixel on. 


* / 
if( _getpixel_w( oldwin.wx, oldwin.wy ) == color ) 
fintersect = TRUE; 
else 


fintersect = FALSE; 
_setcolor( color ); 
_setpixel_w( oldwin.wx, oldwin.wy ); 
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/* Get and test key. */ 
key = _getch(); 
Switch( key ) 


{ 
case 27: /* ESC Quit * / 
_setvideomode( _DEFAULTMODE ); 
exit( @ ); 
case 32: /* SPACE Move no color * / 
fdisplay = MOVE; 
continue; 
case Q: /* Extended code - get next */ 
key = _getch(); 
Switch( key ) 
{ 
case 7/2: /* UP -y * / 
newwin.wy -= yinc; 
break; 
case 7/7: /* RIGHT +x *« / 
newwin.wx += xinc; 
break; 
case 80: /* DOWN +y * / 
newwin.wy += yinc; 
break; 
case /5: /* LEFT =e * / 
newwin.wX -= xinc; 
break; 
case 82: /* INS Draw white * / 
fdisplay = DRAW; 
continue; 
case 83: /* DEL Draw black * / 
fdisplay = ERASE; 
continue; 
} 
break; 
} 


/* Translate window coordinates to view, view to physical. 
* Then check physical to make sure we're on screen. Update screen 
* and position if we are. Ignore if not. 


* / 
view = _getviewcoord_wxy( &newwin ); 
phys = _getphyscoord( view.xcoord, view.ycoord ); 


if( (phys.xcoord >= @) && (phys.xcoord < vc.numxpixels) && 
(phys.ycoord >= @) && (phys.ycoord < vc.numypixels) ) 
{ 
/* If display on, draw to new position, else move to new. */ 
if( fdisplay != MOVE ) 
id 
if( fdisplay == ERASE ) 
_setcolor( @ ); 
_lineto_w( newwin.wx, newwin.wy ); 
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else 


{ 
_setcolor( @ ); 
_moveto_w( newwin.wx, newwin.wy ); 


/* If there was no intersect, erase old pixel. */ 


Vee. LFintersect: ) 
_setpixel_w( oldwin.wx, oldwin.wy ); 


} 

oldwin = newwin; 
} 
else 


oldwin; 


newwin 


} 
exit( @ ); 


706 _ setwritemode 


_ setwritemode 


Description Sets the current logical mode for line drawing. 
#include <graph.h> 
short __ far _setwritemode( short action ); 


action Interaction with existing screen image 


Remarks The _setwritemode function sets the current logical write mode, which is used 
when drawing lines with the _lineto, _ polygon, and _ rectangle functions. 


The action argument defines the write mode. The possible values are _GAND, 
_GOR, _GPRESET, _ GPSET, and _GXOR. See the description of the 
_ putimage functions for more details on these manifest constants. 


Return Value The _setwritemode function returns the previous write mode, or —1 if an error 
occurs. 

Compatibility Standards: None 
16-Bit: DOS 
32-Bit: None 

See Also _getwritemode, _grstatus, _lineto functions, _ polygon functions, _putimage 


functions, _rectangle functions, _setcolor, _setlinestyle 


Example See the example for _ getwritemode. 


Description 


Remarks 


signal 
signal 
Sets interrupt signal handling. 
#include <signal.h> 


void (__cdecl *signal( int sig, void( __ cdecl *func ) 
(int sig [[, int subcode || ) ) ) (int sig ); 


Sig Signal value 
func Function to be executed 
subcode Optional subcode to the signal number 


The signal function allows a process to choose one of several ways to handle an 
interrupt signal from the operating system. 


The sig argument must be one of the manifest constants described in Table R.13 
and defined in SIGNAL.H. 


Table R.13 Signals and Responses 


Value Mode Meaning Default Action 
SIGABRT Real Abnormal Terminates the calling 
termination program with exit code 3 
SIGFPE Real Floating-point error Terminates the calling 
program with exit code 3 
SIGILL Real Illegal instruction Terminates the calling 
program with exit code 3 
SIGINT Real CTRL+C signal Terminates the calling 


program with exit code 3 
SIGSEGV Real Illegal storage access Terminates the calling 
program with exit code 3 


SIGTERM Real Termination request Terminates the calling 
program with exit code 3 


Note that SIGILL, SIGSEGV, and SIGTERM are not generated with DOS. 
They are included for ANSI compatibility. Thus, you can set signal handlers for 
these signals via signal, and you can also explicitly generate these signals by 
calling raise. 
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Note also that signal settings are not preserved in child processes created by calls 
to _exec or _spawn. The signal settings are reset to the default in the child 
process. 


The action taken when the interrupt signal is received depends on the value of 
func. The func argument must be either a function address or one of the manifest 
constants defined in SIGNAL.H and listed below: 


SIG_ DFL 
Uses system-default response. The system-default response for all signals is to 
abort the calling program. The calling process is terminated with exit code 3, 
and control returns to DOS. If the calling program uses stream I/O, buffers 
created by the run-time library are not flushed, but buffers created by the operat- 
ing system are flushed. 


SIG_IGN | 
Ignores interrupt signal. This value should never be given for SIGFPE, since 
the floating-point state of the process 1s left undefined. 


Function address 
Installs the specified function as the handler for the given signal. 


For all signals except SIGFPE, the function is passed the sig argument 
SIGINT and executed. 


For SIGFPE signals, the function is passed two arguments; namely SIGFPE 
and the floating-point error code identifying the type of exception that occurred. 


For SIGFPE, the function pointed to by func is passed two arguments, SIGFPE 
and an integer error subcode, FPE_.xxx; then the function is executed. (See the in- 
clude file FLOAT.H for definitions of the FPE_ xxx subcodes.) The value of func 
is not reset upon receiving the signal. In C programs, SIGFPE is the only constant 
available when the _WINDOWS constant is defined. The _. WINDOWS constant 
is defined by CL options /GA, /GD, /GE, /GW, and /Gw. To recover from floating- 
point exceptions, use setjmp in conjunction with longjmp. (See the example 
under _fpreset.) If the function returns, the calling process resumes execution 

with the floating-point state of the process left undefined. 


If the function returns, the calling process resumes execution immediately follow- 
ing the point at which it received the interrupt signal. This is true regardless of the 
type of signal or operating mode. 


Before the specified function is executed with DOS versions 3.x or earlier, the 
value of func is set to SIG_DFL. The next interrupt signal is treated as described 
above for SIG_ DEL, unless an intervening call to signal specifies otherwise. This 
allows the program to reset signals in the called function. 
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Since signal-handler routines are normally called asynchronously when an inter- 
rupt occurs, it is possible that your signal-handler function will get control when a 
run-time operation is incomplete and in an unknown state. Certain restrictions 
therefore apply to the functions that can be used in your signal-handler routine: 


1. Do not issue low-level or standard input and output routines (e.g., printf, 
_read, _ write, fread). 


2. Do not call heap routines or any routine that uses the heap routines (e.g., 
malloc, _strdup, _ putenv). 


3. Do not use any function that generates a system call (e.g.,__getewd, time). 


4. Do not use the longjmp function unless the interrupt is caused by a floating- 
point exception (i.e., sig is SIGFPE). In this case, the program should first re- 
initialize the floating-point package by means of a call to _fpreset. 


5. Do not use any overlay routines. 


Note With DOS, a program must contain floating-point code if it is to trap the 
SIGFPE exception with the signal function. If your program does not have float- 
ing-point code and it requires the run-time library’s signal-handling code, simply 
declare a volatile double and initialize it to zero: 


volatile double d = Q.@f; 


Return Value The signal function returns the previous value of func associated with the given 
signal. For example, if the previous value of func was SIG_IGN, the return value 
will be SIG_IGN. 


A return value of SIG_ ERR indicates an error, and errno is set to EINVAL. 


Compatibility ‘Standards: ANSI, UNIX 
16-Bit. DOS, QWIN, WIN, WIN DLL 
32-Bit.  DOS32X 


See Also abort, _ exec functions, exit, _ exit, _ fpreset, _ spawn functions 
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Example /* SIGNAL.C illustrates setting up signal interrupt routines. Functions 
illustrated include signal and raise. 


Since C I/0 functions are not safe inside signal routines, the code 
uses conditionals to use system-level DOS services. Another option 
is to set global flags and do any I/0 operations outside the 

Signal handler. 


x * * * * * 


** / 


#include <stdio.h> 
#Hinclude <conio.h> 
#Hinclude <signal.h> 
#Hinclude <process.h> 
#include <stdlib.h> 
#tinclude <dos.h> 
#include <bios.h> 


void ctrlchandler( int sig ); /* Prototypes */ 
void safeout( char *str ); 
int safein( void ); 


void main( void ) 
int ch; 
/* Install signal handler to modify CTRL+C behavior. */ 
if( signal( SIGINT, ctrlchandler ) == SIG _ERR ) 
{ 
fprintf( stderr, "Couldn't set SIGINT\n" ); 
abort(); 
i 


/* Loop prints message to screen asking user to 
* enter Cntl+C--at which point the ctrichandler 
* Signal handler takes control. 

* / 
do 
{ 
printf( "Press Ctrl+C to enter handler.\n" ); 
} 
while( ch = _getch()); /* Discard keystokes */ 


/* A signal handler must take a single argument. The argument can be 
tested within the handler and thus allows a single signal handler 
to handle several different signals. In this case, the parameter 
is included to keep the compiler from generating a warning but is 
ignored because this signal handler only handles one interrupt: 
SIGINT (Ctr1+C). 


x X* * * X 


* / 
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void ctrichandler( int sig ) 


{ 
TG Ce 
Chat’ ‘Scurry & 75 
/* Disallow CTRL+C during handler. */ 
Signal( SIGINT, SIG_IGN ); 
safeout( "User break - abort processing (y|n)? " ); 
c = safein(); 
Stri Ot = -cs 
// safeout( str ); 
safeout( “\r\n" ); 
if( (ec == "y') [|] (c == "Y") ) 
abort(); 
else 
{ 
/* The CTRL+C interrupt must be reset to our handler since 
* by default it is reset to the system handler. 
* / 
Signal( SIGINT, ctrichandler ); 
safeout( "Press Ctri+C to enter handler.\r\n" ); 
} 
} 


/* Outputs a string using system level calls. */ 
void safeout( char *str_ ) 


{ 
union _REGS inregs, outregs; 
inregs.h.ah = QxQe; 
while( *str_) 
{ 
inregs.h.al = *sStrt++t; 
_int86( @x10, &inregs, &outregs ); 
} 
} 


/* Inputs a character using system level calls. */ 
int safein() 


{ 
return _bios_keybrd( _KEYBRD_READ ) & @xff; 
j 
Output Press Ctrl+C to enter handler. 
SG 


User break - abort processing (y|n)? y 
abnormal program termination 
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Description 


Remarks 


Return Value 


Compatibility 


sin Functions 


Calculate sines and hyperbolic sines. 
#include <math.h> 


double sin( double x ); 

double sinh( double x ); 

long double _sinl( long double x ); 
long double _sinhl( long double x ); 


x Angle in radians 


The sin and sinh functions find the sine and hyperbolic sine of x, respectively. The 
_Sinl and _ sinh] functions are the 80-bit counterparts and use an 80-bit, 10-byte 
coprocessor form of arguments and return values. See the reference page on the 
long double functions for more details on this data type. 


The sin functions return the sine of x. If x is large, a partial loss of significance in 
the result may occur, and sin generates a__PLOSS error. If x is so large that signif- 
icance is completely lost, the sin function prints a_TLOSS message to stderr and 
returns 0. In both cases, errno is set to ERANGE. 


The sinh function returns the hyperbolic sine of x. If the result is too large, sinh 
sets errno to ERANGE and returns + HUGE_ VAL. Error handling can be 
changed with the _ matherr function. 


sin, sinh | 
Standards: ANSI, UNIX 
16-Bit: DOS, QWIN, WIN, WIN DLL 


32-Bit: DOS32X 


See Also 


Example 


Output 


sin Functions 


_sinl, _ sinhl 

Standards: None 

16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: None 


acos functions, asin functions, atan functions, cos functions, tan functions 


/* SINCOS.C: This program displays the sine, hyperbolic sine, cosine, 


* and hyperbolic cosine of pi / 2. 
* / 


dEinclude <math.h> 
dEinclude <stdio.h> 


void main( void ) 

{ 
double pi = 3.1415926535; 
double x, y; 


> aa 0 ae 

y = Sin( x ); 

pRIOEre “Sing 2 S20" Key 3 
ye SinhG x J: 

printf( "“sinh( “Ff ) = %4f\n",x, y ); 
y = cost x ); 

printf( "“cos( 4f ) = 4f\n", x, y ); 
y = cosh( x ); 

printf( "“cosh( “fF ) = 4f\n",x, y ); 


Sin( 1.570796 ) = 1.000000 
sinn( 1.570796 ) = 2.301299 
cos( 1.570796 ) = 0.000000 
cosh( 1.570796 ) = 2.509178 
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714. + +_sopen 


Description 


Remarks 


_sopen 


Opens a file for file sharing. 


#include <fentl.h> 
#include <sys\types.h> 
#include <sys\stat.h> 
#include <share.h> 


#include <io.h> Required only for function declarations 


int _sopen( char “filename, int oflag, int shflag |[, int pmode |] ); 


filename Filename 

oflag Type of operations allowed 
shflag Type of sharing allowed 
pmode Permission setting 


The _sopen function opens the file specified by filename and prepares the file for 
subsequent shared reading or writing, as defined by oflag and shflag. The integer 
expression oflag is formed by combining one or more of the following manifest 
constants, defined in the file FCNTL.H. When two or more constants are used to 
form the argument oflag, the constants are combined with the bitwise-OR 
operator (| ). 


Constant Meaning 

_O_APPEND Repositions the file pointer to the end of the file before every 
write operation. 

_O_BINARY Opens file in binary (untranslated) mode. (See fopen for a 
description of binary mode.) 

_O_CREAT Creates and opens a new file. This has no effect if the file 
specified by filename exists. 

_O_EXCL Returns an error value if the file specified by filename exists. 
This applies only when used with _O_ CREAT. 

_O_RDONLY Opens file for reading only. If this flag is given, neither the 
_O_RDWYR flag nor the O_WRONLY flag can be given. 

_O_RDWR Opens file for both reading and writing. If this flag is given, 


neither _O_ RDONLY nor _OQ_ WRONLY can be given. 
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Constant Meaning 

_O_TEXT Opens file in text (translated) mode. (See fopen for a description 
of text mode.) 

_O_TRUNC Opens and truncates an existing file to 0 bytes. The file must 


have write permission; the contents of the file are destroyed. 


_O_WRONLY Opens file for writing only. If this flag 1s given, neither 
_O_RDONLY nor _O_ RDWR can be given. 


The argument shflag is a constant expression consisting of one of the following 
manifest constants, defined in SHARE.H. If SHARE.COM (or SHARE.EXE for 
some versions of DOS) is not installed, DOS ignores the sharing mode. (See your 
system documentation for detailed information about sharing modes.) 


Constant Meaning 


_SH_COMPAT Sets compatibility mode. This is the sharing mode used in the 
_open function in DOS. 


_SH_DENYRW Denies read and write access to file. 
_SH_DENYWR Denies write access to file. 
_SH_DENYRD Denies read access to file. 
_SH_DENYNO Permits read and write access. 


The _sopen function should be used only with DOS version 3.0 and later. Under 
earlier versions of DOS, the shflag argument is ignored. 


The pmode argument is required only when _O_ CREAT 1s specified. If the file 
does not exist, pmode specifies the file’s permission settings, which are set when 
the new file is closed for the first time. Otherwise, the pmode argument is ignored. 
The pmode argument is an integer expression that contains one or both of the 
manifest constants _S_ITIWRITE and _S_IREAD, defined in SYS\STAT.H. 
When both constants are given, they are combined with the bitwise-OR operator 
(|). The meaning of the pmode argument is as follows: 


Value Meaning 
_S_TWRITE Writing permitted 
_S_TREAD Reading permitted 


_S_IREAD|!_S_IWRITE _ Reading and writing permitted 


If write permission is not given, the file 1s read-only. With DOS, all files are 
readable; it is not possible to give write-only permission. Thus, the modes 
_S_IWRITE and _S_TREAD |_S_ITWRITE are equivalent. 


716  _sopen 


Note that with DOS versions 3.x with SHARE installed, a problem occurs when 
opening a new file with _sopen under the following sets of conditions: 


= With oflag set to_O_ CREAT |_O_RDONLY or 
_O_ CREAT |_O_WRONLY, pmode set to _S_TREAD, and shflag set to 
_SH_COMPAT. 


# With oflag set to any combination that includes _O_ CREAT |_O_RDWR, 
pmode set to _S_TIREAD, and shflag set to anything other than 
_SH_COMPAT. 


In either case, the operating system will prematurely close the file during system 
calls made within _.sopen, or the system will generate a sharing violation (INT 
24H). To avoid the problem, open the file with pmode set to _S_TWRITE. After 
closing the file, call _chmod and change the mode back to__.S_IREAD. Another 
solution is to open the file with pmode set to _S_IREAD, oflag set to 
_O_CREAT |_O_RDWR, and shflag set to _SH.COMPAT. 


The _sopen function applies the current file-permission mask to pmode before set- 
ting the permissions (see _ umask). 


Return Value The _sopen function returns a file handle for the opened file. A return value of —1 
indicates an error, and errno is set to one of the following values: 


Value Meaning 


EACCES Given path name is a directory; or the file is read-only but an 
open for writing was attempted; or a sharing violation occurred 
(the file’s sharing mode does not allow the specified operations; 
DOS versions 3.0 and later only). 


EEXIST The _O_ CREAT and _O_ EXCL flags are specified, but the 
named file already exists. 


EINVAL An invalid oflag or shflag argument was given. 
EMFILE No more file handles available (too many open files). 
ENOENT File or path name not found. 

Compatibility Standards: None 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 

See Also _ close, _ creat, fopen, _fsopen, _ open, _ umask 


Example See the example for _ locking. 


Description 
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_ Spawn Functions 


Create and execute a new child process for DOS. 


#include <stdio.h> 


#include <process.h> 


int _spawnl( int mode, char *cmdname, char *arg0, char *arg/, ... char *“argn, 
NULL ); 


int _spawnle( int mode, char *cmdname, char *“arg0, char *arg/, ... char *argn, 
NULL, char **envp ); 


int _spawnlp( int mode, char *cmdname, char *arg0, char *arg1, ... char *“argn, 
NULL); 


int _spawnlpe( int mode, char *cmdname, char *arg0, 
char “arg/,... char *argn, NULL, char **envp ); 


int _spawnv( int mode, char *cmdname, char **argv ); 
int _spawnve( int mode, char *cmdname, char **argyv, char **envp ); 
int _spawnvp( int mode, char *cmdname, char **argv ); 


int _spawnvpe( int mode, char *cmdname, char **argyv, char **envp ); 


mode Execution mode for parent process 
cmdname Path name of file to be executed 
arg0, ... argn List of pointers to arguments 

argv Array of pointers to arguments 


envp Array of pointers to environment settings 
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Remarks 


The _spawn family of functions creates and executes a new child process. 
Enough memory must be available for loading and executing the child process. 
The mode argument determines the action taken by the parent process before and 
during _ spawn. The following values for mode are defined in PROCESS.H: 


Value Meaning 


_P_OVERLAY Overlays parent process with child, destroying the parent (same 
effect as _exec calls). 

_P_WAIT Suspends parent process until execution of child process 1s 
complete (synchronous _ spawn). 


The cmdname argument specifies the file which will be executed as the child 
process, and can specify a full path (from the root), a partial path (from the current 
working directory), or just a filename. If cmdname does not have a filename exten- 
sion or does not end with a period (.), the _spawn function first tries the .COM ex- 
tension, then the .EXE extension, and finally the .BAT extension. This ability to 
spawn batch files is new beginning with Microsoft C version 6.0. 


If cmdname has an extension, only that extension is used. If cmdname ends with a 
period, the _ spawn calls search for cmdname with no extension. The _spawnlp, 
_spawnlpe, _spawnvp, and _spawnvpe routines search for cmdname (using the 
same procedures) in the directories specified by the PATH environment variable. 


If cmdname contains a drive specifier or any slashes (i.e., if it is a relative path 
name), the _spawn call searches only for the specified file and no path searching 
is done. 


Arguments for the Child Process 

Arguments are passed to the child process by giving one or more pointers to char- 
acter strings as arguments in the _ spawn call. These character strings form the ar- 
gument list for the child process. The combined length of the strings forming the 
argument list for the child process must not exceed 128 bytes in real mode. The ter- 
minating null character (’\0’) for each string is not included in the count, but space 
characters (automatically inserted to separate arguments) are included. 


The argument pointers may be passed as separate arguments (_spawnl, 
_spawnle, _spawnlp, and _spawnlpe) or as an array of pointers (_spawnv, 
_spawnve, _spawnvp, and _spawnvpe). At least one argument, arg0 or argyv[0], 
must be passed to the child process. By convention, this argument is the name of 
the program as it might be typed on the command line by the user. (A different 
value will not produce an error.) In real mode, the argv[0] value is supplied by the 
operating system and is the fully qualified path name of the executing program. In 
protected mode, it is usually the program name as it would be typed on the com- 
mand line. i 
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The _spawnl, _spawnle, _spawnlp, and _spawnlpe calls are typically used in 
cases where the number of arguments is known in advance. The arg0 argument is 
usually a pointer to cmdname. The arguments arg/ through argn are pointers to 
the character strings forming the new argument list. Following argn, there must be 
a NULL pointer to mark the end of the argument list. 


The _spawnv, _spawnve, _spawnvp, and _spawnype calls are useful when the 
number of arguments to the child process is variable. Pointers to the arguments are 
passed as an array, argv. The argument argv[0] is usually a pointer to a path name 
in real mode or to the program name in protected mode, and argv[1] through 
argv[n] are pointers to the character strings forming the new argument list. The ar- 
gument argv[n+1] must be a NULL pointer to mark the end of the argument list. 


Environment of the Child Process 

Files that are open when a __spawn call is made remain open in the child process. 
In the _spawnl, _spawnlp, _spawnv, and _spawnvp calls, the child process in- 
herits the environment of the parent. The _spawnle, _ spawnlpe, _spawnve, and 
_Spawnype calls allow the user to alter the environment for the child process by 
passing a list of environment settings through the envp argument. The argument 
envp 1s an array of character pointers, each element of which (except for the final 
element) points to a null-terminated string defining an environment variable. Such 
a string usually has the form 


NAME=value 


where NAME is the name of an environment variable and value is the string value 
to which that variable is set. (Note that value is not enclosed in double quotation 
marks.) The final element of the envp array should be NULL. When envp itself is 
NULL, the child process inherits the environment settings of the parent process. 


The _spawn functions can pass the child process all information about open files, 
including the translation mode, through the C_FILE_INFO entry in the environ- 
ment that is passed in real mode. 


The startup code normally processes this entry and then deletes it from the environ- 
ment. However, if a__spawn function spawns a non-C process, this entry remains 
in the environment. Printing the environment shows graphics characters in the defi- 
nition string for this entry, since the environment information is passed in binary 
form in real mode. It should not have any other effect on normal operations. In 
protected mode, the environment information is passed in text form and therefore 
contains no graphics characters. 


You must explicitly flush (using fflush or _ flushall) or close any stream prior to 
the _spawn function call. 
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Return Value 


Compatibility 


Starting with Microsoft C version 6.0, you can control whether or not the open file 
information of a process will be passed to its child processes. The external varia- 
ble _fileinfo (declared in STDLIB.H) controls the passing of C_FILE_INFO in- 
formation. If _ fileinfo is 0, the C_FILE_INFO information is not passed to the 
child processes. If _ fileinfo is not 0, C_FILE_INFO is passed to child processes. 


By default, _ fileinfo is 0 and thus the C_FILE_ INFO information is not passed 
to child processes. There are two ways to modify the default value of _ fileinfo: 


= Link the supplied object file FILEINFO.OBJ into your program. Use the /NOE 
option to avoid multiple symbol definitions. 


= Set the _fileinfo variable to a nonzero value directly within your C program. 


The return value from a synchronous _ spawn (_P_ WAIT specified for mode) is 
the exit status of the child process. 


The exit status is 0 if the process terminated normally. The exit status can be set to 
a nonzero value if the child process specifically calls the exit routine with a non- 
zero argument. If the child process did not explicitly set a positive exit status, a 
positive exit status indicates an abnormal exit with an abort or an interrupt. A re- 
turn value of —1 indicates an error (the child process is not started). In this case, 
errno is set to one of the following values: 


Value Meaning | 

E2BIG In DOS, the argument list exceeds 128 bytes, or the space 
required for the environment information exceeds 32K. 

EINVAL The mode argument is invalid. 

ENOENT The file or path name is not found. 

ENOEXEC The specified file is not executable or has an invalid 


executable-file format. 
ENOMEM Not enough memory is available to execute the child process. 


Note that signal settings are not preserved in child processes created by calls to 
_Spawn routines. The signal settings are reset to the default in the child process. 


Standards: None 
16-Bit: DOS 
32-Bit: DOS32X 


To ensure proper overlay initialization and termination, do not use the setjmp or 
longjmp function to enter or leave an overlay routine. 


See Also 


Example 


dFin 
din 


cha 
{ 


Fs 


VOl 
{ 
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abort, atexit, _ exec functions, exit, _ exit, _ onexit, system 


SPAWN.C: This program accepts a number in the range 1 - 8 from the 
command line. Based on the number it receives, it executes one of the 
eight different procedures that spawn the process named child. For 
some of these procedures, the CHILD.EXE file must be in the 

Same directory; for others, it only has to be in the same path. 


clude <stdio.h> 
clude <process.h> 


r *my_envL] = 


"THIS=environment will be", 
“"PASSED=to child.exe by the", 
" SPAWNLE=and", 

" SPAWNLPE=and", 

" SPAWNVE=and", 

" SPAWNVPE=functions", 

NULL 


d main( int argc, char *argv[] ) 


char *args[4]; 
int result; 


/* Set up parameters to be sent: */ 
argsl@].= "child": 
argsLl1] = “spawn??"; 
argsL2] = "two"; 
args[3] = NULL; 
switch (argv[L1][Q@]) /* Based on first letter of argument */ 
{ 
"ease. ts 
_spawnl( _P_WAIT, argv[2], argv[2], "_spawnl", "two", NULL ); 
break; 
case ‘'2': 
_spawnie( _P_WAIT, argv[2], argv[2], "_spawnle", "two", 
NULL, my_env ); 
break; 
case ‘'3': 
_spawnlp( _P_WAIT, argv[2], argv[2], "_spawnlp", "two", NULL ); 
break; 
case ‘'4'; 
_Spawnlpe( _P_WAIT, argvlL2], argvlL2], "_spawnlpe", "two", 
NULL, my_env ); 
break; 
case '5': 
_spawnv( _P_OVERLAY, argv[2], args ); 
break; 
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case ‘6': 
_Spawnve( _P_OVERLAY, argvl2], args, my_env ); 
break; 
case '/': | 
_Spawnvp( _P_OVERLAY, argv[2], args ); 
break; 
case '8': 
_spawnvpe( _P_OVERLAY, argv[2], args, my_env ); 
break; 
default: 
printf( "SYNTAX: SPAWN <1-8> <childprogram>\n" ); 
exit( 1 ); 
} 
printf( "\n\nReturned from SPAWN! \n" ); 


Description 


Remarks 


Return Value 
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_ splitpath 
Breaks a path name into components. 


#include <stdlib.h> 


void _splitpath( char *path, char *drive, char *dir, char *fname, char “ext ); 


path Full path name 
drive Drive letter 
dir Directory path 
fname Filename 

ext File extension 


The _splitpath routine breaks a full path name into its four components. The path 
argument should point to a buffer containing the complete path name. The maxi- 
mum size necessary for each buffer is specified by the manifest constants 
_MAX_ DRIVE, _MAX_ DIR, _MAX_ FNAME, and _MAX_ EXT, defined in 
STDLIB.H. The other arguments point to the buffers used to store the path-name 
elements: 


Buffer Description 

drive Contains the drive letter followed by a colon (:) if a drive is specified in 
path. 

dir Contains the path of subdirectories, if any, including the trailing slash. 
Forward slashes (/ ), backslashes (\ ), or both may be present in path. 

jname Contains the base filename without any extensions. 

ext Contains the filename extension, if any, including the leading period (.). 


The return parameters will contain empty strings for any path-name components 
not found in path. You can pass a NULL pointer to _ splitpath for any component 
you don’t wish to receive. 


None. 
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Compatibility Standards: None 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 

See Also _fullpath, _makepath 


Example /* MAKEPATH.C */ 
#Hinclude <stdlib.h> 
#tinclude <stdio.h> 


void main( void ) 


{ 
char path_buffer[_MAX_PATH]; 
char drivel_MAX_DRIVE]; 
char dir[l_MAX_DIR]; 
char fname[_MAX_FNAME]; 
char ext[_MAX_EXT]; 
_makepath( path_buffer, "c", "\\c7@\\clibref\\", “makepath", "c" ); 
printf( "Path created with _makepath: %s\n\n", path_buffer ); 
_Ssplitpath( path_buffer, drive, dir, fname, ext ); 
printf( "Path extracted with _splitpath:\n" ); 
printf( " Drive: %s\n", drive ); 
printf( " Dir: %s\n", dir ); 
printf( " Filename: %s\n", fname ); 
printt( ” Ext: 2s\n"» ext )s 

I 

Output Path created with _makepath: c:\c7@\clibref\makepath.c 


Path extracted with _splitpath: 
Drive: Cc: 
Dir: \c/7@\clibref\ 
Filename: makepath 
EXUy 2c 


Description 


Remarks 


Return Value 


Compatibility 
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sprintf, — snprintf 
Write formatted data to a string. 
#include <stdio.h> 


int sprintf( char *buffer, const char *format |, argument] ... ); 


int _snprintf( char *buffer, size_t count, const char *format [[, argument] ... )5 


buffer Storage location for output 

format Format-control string 

argument Optional arguments 

count Maximum number of bytes to store 


The sprintf function formats and stores a series of characters and values in buffer. 
Each argument (if any) is converted and output according to the corresponding for- 
mat specification in the format. The format consists of ordinary characters and has 
the same form and function as the format argument for the printf function. (See 
printf for a description of the format and arguments.) A null character is appended 
to the end of the characters written, but is not counted in the return value. 


The _ snprintf function differs from sprintf in that it stores no more than count 
characters to buffer. 


Both the sprintf and _ snprintf functions return the number of characters stored in 
buffer, not counting the terminating null character. For _ snprinttf, if the number of 
bytes required to store the data exceeds count, then count bytes of data are stored 
in buffer and —1 is returned. 


sprintf 
Standards: ANSI, UNIX 
16-Bit: DOS, QWIN, WIN 


32-Bit: DOS32X 
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_snprintf 


Standards: None 


16-Bit: DOS, QWIN, WIN 
32-Bit: DOS32X 
See Also fprintf, printf, sscanf 


Example /* SPRINTF.C: This program uses sprintf to format various data and 
* Dlace them in the string named buffer. 
* / 
dFinclude <stdio.h> 


void main( void ) 


{ 
char buffer[200], s[] = "computer", c = 'I1'; 
int 1 = B55 75 
float fp = 1.7320534; 
/* Format and print various data: */ 
j = sprintf( buffer, "\tString: RSNA SDS 
j += -sprintt( buffer + j,.“\tCharacter: %c\n", c ): 
j t= sprintf( buffer + j, "\tInteger: tains 7 2 
j += sprintf( buffer + j, "\tReal: BENG 3 FD. os 
printf( "Output:\n%s\ncharacter count = %d\n", buffer, j ); 

} 

Output Output: 


String: computer 
Character: | 
Integer: 35 

Real: 1.732053 


character count = 71 


Description 


Remarks 


Return Value 


Compatibility 


See Also 
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sari, _ sari 


Calculate the square root. 


#include <math.h> 


double sqrt( double x ); 


long double _ sqrtl( long double x ); 


Nonnegative floating-point value 


The sqrt functions calculate the square root of x. The _sqrtl function is the 80-bit 
counterpart and uses an 80-bit, 10-byte coprocessor form of arguments and return 


values. 


The sqrt functions return the square-root result. If x is negative, the function prints 
a _DOMAIN error message to stderr, sets errno to EDOM, and returns 0. 


Error handling can be modified by using the _matherr or _ matherrl routine. 


sqrt 
Standards: 
16-Bit: 
32-Bit: 


_sqrtl 
Standards: 
16-Bit: 
32-Bit: 


ANSI, UNIX 
DOS, QWIN, WIN, WIN DLL 
DOS32X 


None 
DOS, QWIN, WIN, WIN DLL 


None 


exp, log, _matherr, pow 


728 sqrt, _ sqrtl 


Example /* SQRT.C: This program calculates a square root. */ 
#Hinclude <math.h> 
#Hinclude <stdio.h> 
fHinclude <stdlib.h> 


void main( void ) 


{ 
double question = 45.35, answer; 
answer = sqrt( question ); 
if( errno == EDOM ) 
printf( "Domain error\n" ); 
else 
printf( "The square root of %.2f is %.2f\n", question, answer ); 
} 


Output The square root of 45.35 is 6.73 


Description 


Remarks 


Return Value 


Compatibility 


See Also 


srand 729 


srand 


Sets a random starting point. 
#include <stdlib.h> Required only for function declarations 
void srand( unsigned int seed ); 


seed Seed for random-number generation 


The srand function sets the starting point for generating a series of pseudorandom 
integers. To reinitialize the generator, use 1 as the seed argument. Any other value 
for seed sets the generator to a random starting point. 


The rand function is used to retrieve the pseudorandom numbers that are gener- 
ated. Calling rand before any call to srand will generate the same sequence as 
calling srand with seed passed as 1. 


None. 


Standards: ANSI, UNIX 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 


rand 
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Example /* RAND.C: This program seeds the random number generator with the 
* time, then displays 20 random integers. 
* / 


dHinclude <stdlib.h> 
dAinclude <stdio.h> 
d#Finclude <time.h> 


void main( void ) 
A 
int i; 


/* Seed the random number generator with current time so that 
* the numbers will be different every time we run. 

* / 

srand( (unsigned)time( NULL ) ); 


/* Display 10 numbers. */ 
for( i = 0; i < 10; it+ ) 
printf( " %6d\n", rand() ); 


Output 19471 
16395 
8268 
15582 
6489 
28356 
27042 
5276 
23070 
10930 


Description 


Remarks 


Return Value 


Compatibility 


See Also 


sscanf 731 


sscanf 


Reads formatted data from a string. 
#include <stdio.h> 


int sscanf( const char *buffer, const char *format ||, argument | ... )5 


buffer Stored data 
format Format-control string 
argument Optional arguments 


The sscanf function reads data from buffer into the locations given by each 
argument. Every argument must be a pointer to a variable with a type that corre- 
sponds to a type specifier in format. The format controls the interpretation of the 
input fields and has the same form and function as the format argument for the 
scanf function; see scanf for a complete description of format. 


The sscanf function returns the number of fields that were successfully converted 
and assigned. The return value does not include fields that were read but not 
assigned. 


The return value is EOF for an attempt to read at end-of-string. A return value of 
0 means that no fields were assigned. 


Standards: ANSI, UNIX 
16-Bit: DOS, QWIN, WIN 
32-Bit: DOS32X 


fscanf, scanf, sprintf 


732 sscanf 


Example /* SSCANF.C: This program uses sscanf to read data items from 
* a String named tokenstring, then displays them. 
* / 
d#Finclude <stdio.h> 


void main( void ) 


{ 
char tokenstringL] = "15 12 14..."; 
char s[8l]; 
char Cc; 
int 1; 
float fp; 
/* Input various data from tokenstring: */ 
sscanf( tokenstring, "%s", s ); 
sscanf( tokenstring, "%c", &c ); 
sscanf( tokenstring, "4d", &i ); 
sscanf( tokenstring, "%f", &fp ); 
/* Qutput the data read */ 
printf( "String = %s\n", s ); 
printf( "Character = %c\n", c ); 
printf( "Integer: = %d\n", 7 ); 
printf( "Real: = “f\n", fp ); 

} 

Output String = 15 
Character = 1 
Integer: = 15 


Real: = 15.000000 


Description 


Remarks 


Return Value 


Compatibility 


Example 
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_ Stackavail 
Gets the size of the stack available. 
#include <malloc.h> Required only for function declarations 


size_t _stackavail( void ); 


The _ stackavail function returns the approximate size (in bytes) of the stack 
space available for dynamic memory allocation with _ alloca. 


The _ stackavail function returns the size in bytes as an unsigned integer value. 
Standards: None 

16-Bit: DOS, QWIN, WIN, WIN DLL 

32-Bit: None 


/* ALLOCA.C: Checks the stack space available before and after using 
* alloca to allocate space on the stack. As _alloca is incompatible 
* with optimizing, compile with optimizations disabled (/0d). 

a / 


d#Finclude <malloc.h> 
#Ainclude <stdio.h> 


Output 


void main( void ) 


{ 

char *buffer; 

printf( "Bytes available on stack: 4u\n", _stackavail() ); 

/* Allocate memory for string. */ 

buffer = _alloca( 120 * sizeof( char ) ); 

printf( "Enter a string: ™ ); 

gets( buffer ); 

printf( "You entered: %s\n", buffer ); 

printf( "Bytes available on stack: %u\n", _stackavail() ); 
I 


Bytes available on stack: 2028 
Enter a string: How much stack space will this string take? 


You entered: How much stack Space will this string take? 
Bytes available on stack: 1902 
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Description 


Remarks 


Return Value 


_ Stat 


Gets status information on a file. 


#include <sys\types.h> 


#include <sys\stat.h> 


int _ stat( char *pathname, struct _stat *buffer ); 


pathname 


buffer 


Path name of existing file 


Pointer to structure that receives results 


The _ stat function obtains information about the file or directory specified by 
pathname and stores it in the structure pointed to by buffer. The _stat structure, 
defined in the file SYS\STAT.H, includes the following fields: 


Field 


st_atime 
st_ctime 
st_dev 


st_mode 


st_mtime 
st_nlink 
st_rdev 


st_size 


Value 


Time of last access of file. 
Time of creation of file. 


Drive number of the disk containing the file (same as st_rdev). Real 
mode only. 


Bit mask for file-mode information. The _S_ IFDIR bit is set if 
pathname specifies a directory; the _S_IFREG bit is set if pathname 
specifies an ordinary file. User read/write bits are set according to the 
file’s permission mode; user execute bits are set according to the 
filename extension. 

Time of last modification of file.. 

Always 1. 

Drive number of the disk containing the file (same as st_ dev). Real 
mode only. 


Size of the file in bytes. 


Note that if pathname refers to a device, the size and time fields in the _ stat struc- 
ture are not meaningful. Also, as STAT.H uses the dev_t type, which is defined in 
TYPES.H, you must include TYPES.H before STAT.H in your code. 


The _ stat function returns 0 if the file-status information is obtained. A return 
value of —1 indicates an error; also, errno is set to ENOENT, indicating that the 
filename or path name could not be found. 
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Compatibility Standards: UNIX 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 


See Also 


Example 


Output 


Use _stat for compatibility with ANSI naming conventions of non-ANSI func- 
tions. Use stat and link with OLDNAMES.LIB for UNIX compatibility. 


—_access, _ fstat 


/* STAT.C: This program uses the _stat function to report information 
* about the file named STAT.C. 
* / 


dFinclude <time.h> 
#Finclude <sys\types.h> 
dFinclude <sys\stat.h> 
#Finclude <stdio.h> 


void main( void ) 


{ 
struct _stat buf; 
int fh, result; 
char buffer[L] = "A line to output"; 
/* Get data associated with "Stat.c": */ 
result = _stat( "“stat.c", &buf ); 
/* Check if statistics are valid: */ 
if( result != @ ) 
perror( "Problem getting information" ); 
else 
{ 
/* Qutput some of the statistics: */ 
printf( "File size : \d\n", buf.st_size ); 
printf( "Drive : Zc:\n", buf.st_dev + ‘'A" ): 
printf( "Time modified : %s", ctime( &buf.st_atime ) ); 
} 
} 
File size > 761 
Drive a Oe 


Time modified : Mon Jun 14 12:20:08 1999 
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Description 


Remarks 


Return Value 


Compatibility 


See Also 


_ Status87 


Gets the floating-point status word. 
#include <float.h> 


unsigned int _ status87( void ); 


The _status87 function gets the floating-point status word. The status word is a 
combination of the 8087/80287/80387 status word and other conditions detected 
by the 8087/80287/80387 exception handler, such as floating-point stack overflow 
and underflow. 


The bits in the value returned indicate the floating-point status. See the FLOAT.H 
include file for a complete definition of the bits returned by _status87. 


Note that many of the math library functions modify the 8087/80287 status word, 
with unpredictable results. Return values from _clear87 and _status87 become 
more reliable as fewer floating-point operations are performed between known 
states of the floating-point status word. 


Standards: None 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 


_clear87, _control87 


Example /* STATUS87.C: This program creates various floating-point errors and 
* then uses _status8/7 to display messages indicating these problems. 
* Compile this program with optimizations disabled (/0d). Otherwise, 
* the optimizer will remove the code related to the unused floating- 
* point values. 


* / 


d#Finclude <stdio.h> 
##include <float.h> 
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void main( void ) 


{ 
double a = le-4@, b; 
TloOdc: 5.“ 
printf( "Status = %.4x - clear\n", status8/() ); 
/* Assignment into y is inexact & underflows: */ 
y = a; 
printf( "Status = %.4x - inexact, underflow\n", _status8/7() ); 
/* y is denormal: */ 
b= y; 
printf( "Status = %.4x - inexact underflow, denormal\n", _status87() ); 
/* Clear user 8087: */ 
_clear87(); 

} 

Output Status = @00@ - clear 
Status = 0030 - inexact, underflow 
Status = 0032 - inexact underflow, denormal 
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Description 


Remarks 


Return Value 


Compatibility 


Sstreat, _ fstrcat 


Append a string. 
#include <string.h> Required only for function declarations 


char *streat( char *string/, const char *string2 ); 


char __ far * __ far _fstreat( char __ far *string/, const char __far *string2 ); 


string 1 Destination string 


string2 Source string 


The streat and _ fstreat functions append string2 to string/, terminate the result- 
ing string with a null character, and return a pointer to the concatenated string 
(string). | 


The streat and _ fstreat functions operate on null-terminated strings. The string ar- 
guments to these functions are expected to contain a null character (’\0’) marking 
the end of the string. No overflow checking is performed when strings are copied 
or appended. 


The _fstreat function is a model-independent (large-model) form of the streat 
function. The behavior and return value of _fstrcat are identical to those of the 
model-dependent function streat, with the exception that the arguments and return 
values are far pointers. 


The return values for these functions are described above. 


strcat 
Standards: ANSI, UNIX 
16-Bit: DOS, QWIN, WIN, WIN DLL 


32-Bit: DOS32X 


See Also 


Example 


Output 


strcat, _fstrcat 


_fstreat 


Standards: None 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: None 


strncat, strnemp, strncpy, _strnicmp, strrchr, strspn 


/* STRCPY.C: This program uses strcpy and strcat to build a phrase. */ 


#Hinclude <string.h> 
dHinclude <stdio.h> 


void main( void ) 


{ 
char string[l80]; 
strcpy( string, "Hello world from " ); 
Strcat( string, "strcpy " ); 
strcat( string, "and " ); 
Strcat( string, “strcat!" ); 
printf( "String = %s\n", string ); 
} 


String = Hello world from strcpy and strcat! 
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Strehr, _ fstrchr 
Description Find a character in a string. 
#include <string.h> Required only for function declarations 


char *strchr( const char *string, int c ); 


char __ far * __ far _fstrchr( const char __ far *string, int c ); 


string Source string 
C Character to be located 
Remarks The strehr and _ fstrchr functions return a pointer to the first occurrence of c (con- 


verted to char) in string. The converted character c may be the null character 
(?\0’); the terminating null character of string is included in the search. The func- 
tion returns NULL if the character is not found. 


The strchr and _fstrchr functions operate on null-terminated strings. The string 
arguments to these functions are expected to contain a null character (?\0’) mark- 
ing the end of the string. 


The _fstrchr function is a model-independent (large-model) form of the strchr 
function. The behavior and return value of _fstrchr are identical to those of the 
model-dependent function strehr, with the exception that the arguments and re- 
turn values are far. 


Return Value The return values for these functions are described above. 
Compatibility strchr 

Standards: ANSI, UNIX 

16-Bit: DOS, QWIN, WIN, WIN DLL 


32-Bit: DOS32X 


sirchr, _ fstrchr 741 


_fstrchr 
Standards: None 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: None 
See Also strcspn, strncat, strncmp, strncpy, _strnicmp, strpbrk, strrchr, strspn, strstr 


Example /* STRCHR.C: This program illustrates searching for a character with 
* Strchr (search forward) or strrchr (search backward). 
* / 


#Finclude <string.h> 
d#Finclude <stdio.h> 


At “Che OR Ts 


char stringL] = "The quick brown dog jumps over the lazy fox"; 
char fmtl1[] = ? 1 2 3 4 Os 
char fmt2[] = "12345678901234567890123456789012345678901234567890"; 


void main( void ) 
{ 
char *pdest; 
int result; 


printf( "String to be searched: \n\t\t%s\n", string ); 
printf( "\t\t%s\n\t\t%s\n\n", fmtl, fmt2 ); 
printf( “Search char:\t%c\n", ch ); 


/* Search forward. */ 
pdest = strchr( string, ch ); 
result = pdest - string + 1; 
if( pdest != NULL ) 
printf( "Result:\tfirst %c found at position %d\n\n", ch, result ); 
else 
printf( "Result:\t%c not found\n" ); 


/* Search backward. */ 
pdest = strrchr( string, ch ); 
result = pdest - string + 1; 
if( pdest != NULL ) 
printf( "Result:\tlast %c found at position 4%d\n\n", ch, result ); 
else 
printf( "Result:\t%c not found\n" ); 


142 


Output 


strchr, _ fstrehr 


String to be searched: 
The quick brown dog jumps over the lazy fox 
1 2 3 4 5 
12345678901234567890123456789012345678901234567890 


Search char: r 
Result: first r found at position 12 


Result: last r found at position 3@ 


Description 


Remarks 


Return Value 


strcmp, _fstremp 743 


strcmp, _ fstremp 


Compare strings. 
#include <string.h> Required only for function declarations 


int stremp( const char *string/, const char *string2 ); 


int __ far _fstremp( const char __ far *string/, const char __ far *string2 ); 


string 1 String to compare 


string2 String to compare 


The stremp and _fstremp functions compare string/ and string2 lexicographi- 
cally and return a value indicating their relationship, as follows: 


Value Meaning 

<0 string 1 less than string2 

= 0 string 1 identical to string2 
>0 string! greater than string2 


The stremp and _fstremp functions operate on null-terminated strings. The string 
arguments to these functions are expected to contain a null character (’\0’) mark- 
ing the end of the string. 


The _fstremp function is a model-independent (large-model) form of the stremp 
function. The behavior and return value of _fstremp are identical to those of the 
model-dependent function stremp, with the exception that the arguments are far 
pointers. 


Both the _ stricmp function (described later in this book) and the _ strempi func- 
tion compare strings by first converting them to their lowercase forms. 


Note that two strings containing characters located between ’Z’ and ’a’ in the 
ASCII table ([’, ’V,’]’, ?%’, ’_’, and ’*’) compare differently depending on their 
case. For example, the two strings, "ABCDE" and "ABCD*", compare one way if 
the comparison is lowercase ("abcde" > "abcd*") and compare the other way 
("ABCDE" < "ABCD*") if it is uppercase. 


The return values for these functions are described above. 
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Compatibility strcmp 
Standards: ANSI, UNIX 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X _— 
_fstremp 


Standards: None 


16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: None 
See Also memcmp, _memicmp, strncat, strncmp, strncpy, _strnicmp, strrchr, strspn 


Example /* STRCMP.C */ 
#Hinclude <string.h> 
#Finclude <stdio.h> 


char stringl[] = "The quick brown dog jumps over the lazy fox"; 
char string2[ ] "The QUICK brown dog jumps over the lazy fox"; 


void main( void ) 
{ 
char tmp[20]; 
int result; 


/* Case sensitive */ 
printf( “Compare strings:\n\t%s\n\t%s\n\n", stringl, string2 ); 
result = strcmp stringl, string2 ); 
if( result > @ ) 
strcpy( tmp, "greater than" ); 
else if( result < @ ) 
strcpy( tmp, "less than" ); 
else | 
strcpy( tmp, “equal to" ); 
PriNntte ~\esorcmps String 1 is %s string 2\n", tmp ); 


/* Case insensitive (could use equivalent _stricmp) */ 
result = _stricmp( stringl, string2 ); 
if( result > @ ) 
strcpy( tmp, "greater than" ); 
else if( result < @ ) 
— strcpy( tmp, “less than" ); 
else 
strcpy( tmp, "equal to" ); 
printf( "\t_stricmp: String 1 is %s string 2\n", tmp ); 
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Output Compare strings: 
The quick brown dog jumps over the lazy fox 


The QUICK brown dog jumps over the lazy fox 


strcmp: String 1 is greater than string 2 
_stricmp: String 1 1s equal to string 2 


746 ~_—sStrcoll 
sircoll 
Description Compares strings using locale-specific information. 
#include <string.h> Required only for function declarations 


int strcoll( const char *string/, const char *string2 ); 


string 1 String to compare 
string2 String to compare 
Remarks The strcoll function compares string/ and string2 in a manner determined by the 
LC_COLLATE macro and returns a value indicating their relationship, as 
follows: 
Value Meaning 
<0 string! less than string2 
= 0 string] identical to string2 
>0 string] greater than string2 


For more information on the LC_COLLATE macro, see the setlocale function. 


The strcoll function operates on null-terminated strings. The string arguments to 
these functions are expected to contain a null character (’\0’) marking the end of 
the string. 


The strcoll function differs from stremp in that it uses locale-specific information 
to provide locale-specific collating sequences. 


Return Value The return value for this function is described above. 
Compatibility Standards: ANSI 

16-Bit: DOS, QWIN, WIN, WIN DLL 

32-Bit: DOS32X 


See Also localeconv, setlocale, strcmp, strncmp, strxfrm 


Description 


Remarks 


Return Value 


Compatibility 


See Also 


strepy, _ fstrcpy 747 


strcpy, _ fstrcepy 


Copy a string. 
#include <string.h> Required only for function declarations 


char *strepy( char *string/, const char *string2 ); 


char __ far * __ far _fstrepy( char __ far *string/, const char __far *string2 ); 


string 1 Destination string 


string2 Source string 


The strepy function copies string2, including the terminating null character, to the 
location specified by string/, and returns string]. 


The strepy and _fstrepy functions operate on null-terminated strings. The string 
arguments to these functions are expected to contain a null character (’\0’) mark- 
ing the end of the string. No overflow checking is performed when strings are 
copied or appended. 


The _fstrepy function is a model-independent (large-model) form of the strepy 
function. The behavior and return value of _fstrepy are identical to those of the 
model-dependent function strepy, with the exception that the arguments and 
return values are far pointers. 


The return values for these functions are described above. 


strcepy 

Standards: ANSI, UNIX 

16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 

_fstrepy 

Standards: None 

16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: None 


strcat, strcmp, strncat, strncmp, strnepy, _strnicmp, strrchr, strspn 
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Example /* STRCPY.C: This program uses strcpy and strcat to build a phrase. */ 


#Finclude <string.h> 
##include <stdio.h> 


void main( void ) 
{ 
char string[80]; 


strcepy( string, "Hello world from" ); 
streat( string, "strcpy " ); 

strcat( string, "and " ); 

strceat( string, "strcat!" ); 

printf( "String = %s\n", string ); 


Output String = Hello world from strcpy and strcat! 


strespn, _ fstrespn 749 
Strespn, _ fstrcspn 
Description Find a substring in a string. 
#include <string.h> Required only for function declarations 


size_t strespn( const char *string/, const char *string2 ); 


size_t __far _fstrespn( const char __ far *string/, const char __ far *string2 ); 


string 1 Source string 
string2 Character set 
Remarks The strespn functions return the index of the first character in string] belonging to 


the set of characters specified by string2. This value is equivalent to the length of 
the initial substring of string/ consisting entirely of characters not in string2. Ter- 
minating null characters are not considered in the search. If string] begins with a 

character from string2, strespn returns 0. 


The strespn and _ fstrespn functions operate on null-terminated strings. The 
string arguments to these functions are expected to contain a null character (’\0’) 
marking the end of the string. 


The _ fstrespn function is a model-independent (large-model) form of the strespn 
function. The behavior and return value of _fstrespn are identical to those of the 
model-dependent function strespn, with the exception that the arguments and 
return values are far. 


Return Value The return values for these functions are described above. 
Compatibility strcespn 

Standards: ANSI, UNIX 

16-Bit: DOS, QWIN, WIN, WIN DLL 


32-Bit: DOS32X 
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_fstrespn 


Standards: None 


16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: None 
See Also strncat, strncemp, strnepy, _strnicmp, strrchr, strspn 


Example /* STRCSPN.C */ 
#tinclude <string.h> 
feinclude <stdio.h> 


void main( void ) 


{ 

char string[] = "xyzabc"; 

int pos; 

pos = strcspn( string, "abc" ); 

printf( "First a, b or c in %s is at character %4d\n", string, pos ); 
} 


Output First a, b or c in xyzabc is at character 3 


Description 


Remarks 


Return Value 


Compatibility 


See Also 
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_ Strdate 


Copies a date to a buffer. 
#include <time.h> 
char *_strdate( char *datestr ); 


datestr Current date 


The _strdate function copies the date to the buffer pointed to by datestr, formatted 


mm/dd/yy 


where mm is two digits representing the month, dd is two digits representing the 
day of the month, and yy is the last two digits of the year. For example, the string 


12/05/99 
represents December 5, 1999. 
The buffer must be at least nine bytes long. 


The _strdate function returns a pointer to the resulting text string datestr. 


Standards: None 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 


asctime, ctime, gmtime, localtime, mktime, time, _ tzset 


752  ~ _Strdate 


Example /* STRTIME.C */ 
dEinclude <time.h> 
#Hinclude <stdio.h> 


void main( void ) 

{ 
char dbuffer [9]; 
char tbuffer [9]; 


_Strdate( dbuffer ); 

printf( "The current date is %s \n", dbuffer ); 

_strtime( tbuffer ); 

printf( "The current time is %s \n", tbuffer ); 
} 


Output The current date is 06/20/99 
The current time is 09:33:13 


Description 


Remarks 


Return Value 


_ Strdup Functions 753 


_ $Strdup Functions 


Duplicate strings. 
#include <string.h> Required only for function declarations 


char *_strdup( const char *string ); 
char __ far * __ far _fstrdup( const char __ far *string ); 


char __ near * __ far _nstrdup( const char __ far *string ); 


string Source string 


The _strdup function allocates storage space (with a call to malloc) for a copy of 
string and returns a pointer to the storage space containing the copied string. The 
function returns NULL if storage cannot be allocated. 


The _fstrdup and _nstrdup functions provide complete control over the heap 
used for string duplication. The _strdup function returns a pointer to a copy of the 
string argument. The space for the string is allocated from the heap specified by 
the memory model in use. In large data models (that is, compact-, large-, and huge- 
model programs), _strdup allocates space from the far heap. In small data models 
(tiny-, small-, and medium-model programs), _ strdup allocates space from the 
near heap. 


The _strdup, _fstrdup, and _nstrdup functions operate on null-terminated 
strings. The string arguments to these functions are expected to contain a null char- 
acter (’\0’) marking the end of the string. 


The _fstrdup function returns a far pointer to a copy of the string allocated in far 
memory (the far heap). As with the other model-independent functions, the syntax 
and semantics of these functions correspond to those of _strdup except for the 
sizes of the arguments and return values. The _nstrdup function returns a near 
pointer to a copy of the string allocated in the near heap (in the default data 
segment). 


The return values for these functions are described above. 
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Compatibility _strdup 
Standards: None 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 


_fstrdup, _nstrdup 
Standards: None 


16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: None 
See Also strcat, strcmp, strncat, strncmp, strncpy, _strnicmp, strrchr, strspn 


Example /* STRDUP.C */ 
#Hinclude <string.h> 
#Finclude <stdio.h> 
4#FHinclude <conio.h> 
#Hinclude <dos.h> 


void main( void ) 

{ 
char buffer[] = "This is the buffer text"; 
char *newstring; 


printf( "Original: %s\n", buffer ); 
newstring = _strdup( buffer ); 
printf( "Copy: “Ss\n", newstring ); 


Output Original: This is the buffer text 
Copy: This is the buffer text 


Description 


Remarks 


Strerror, _ strerror 755 


Strerror, _strerror 


Gets a system error message (Strerror) or prints a user-supplied error message 
(_strerror). 


#include <string.h> Required only for function declarations 


char *strerror( int errnum ); 


char *_strerror( char *string ); 


errnum Error number 


string User-supplied message 


The strerror function maps errnum to an error-message string, returning a pointer 
to the string. The function itself does not actually print the message; for that, you 
need to call an output function such as fprinttf: 


if (( _access( “datafile",2 )) == -1 ) 
fprintf( stderr, strerror(NULL) ); 


If string is passed as NULL, _strerror returns a pointer to a string containing the 
system error message for the last library call that produced an error. The error- 
message string is terminated by the newline character (’\n’). 


If string is not equal to NULL, then _strerror returns a pointer to a string contain- 
ing (in order) your string message, a colon, a space, the system error message for 
the last library call producing an error, and a newline character. Your string mes- 
sage can be a maximum of 94 bytes long. 


Unlike perror, _ strerror alone does not print any messages. To print the message 
returned by _strerror to stderr, your program will need an fprintf statement, as 
shown in the following lines: 


if (( _access( "datafile",2 )) == -1 ) 
fprintf( stderr, _strerror(NULL) ); 


The actual error number for _ strerror is stored in the variable errno. The system 
error messages are accessed through the variable sys_errlist, which is an array 
of messages ordered by error number. The _strerror function accesses the 
appropriate error message by using the errno value as an index to the variable 
sys_errlist. The value of the variable sys_nerr is defined as the maximum num- 
ber of elements in the sys_errlist array. 
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Return Value 


Compatibility 


See Also 


Example 


To produce accurate results, _strerror should be called immediately after a 
library routine returns with an error. Otherwise, the errno value may be overwrit- 
ten by subsequent calls. 


Note that the _strerror function under Microsoft C version 5.0 is identical to 
the version 4.0 strerror function. The name was altered to permit the inclusion 
in Microsoft C version 5.0 of the ANSI-conforming strerror function. The 
_Strerror function is not part of the ANSI definition but is instead a Microsoft 
extension to it; it should not be used where portability is desired. For ANSI com- 
patibility, use strerror instead. 


The strerror and _strerror functions return a pointer to the error-message string. 
The string can be overwritten by subsequent calls to strerror or _ strerror, 
respectively. 


strerror 

Standards: ANSI 

16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 

_Strerror 


Standards: None 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 


clearerr, ferror, perror 


See the example for perror. 


Description 


Remarks 


stritime 757 
sirttime 
Formats a time string. 
#include <time.h> Required only for function declarations 


size_t strftime( char *string, size_t maxsize, const char “format, 
const struct tm *timeptr ); 


string Output string 

maxsize Maximum length of string 
format Format control string 
timeptr tm data structure 


The strftime function formats the tm time value in timeptr according to the sup- 
plied format argument and stores the result in the buffer string. At most, maxsize 
characters are placed in the string. 


The format argument consists of one or more codes; as in printf, the formatting 
codes are preceded by a % sign. Characters that do not begin with a % sign are 
copied unchanged to string. The LC_ TIME category of the current locale affects 
the output formatting of strftime. 


The formatting codes for strftime are listed below: 


Format Description 

Joa Abbreviated weekday name 

JA Full weekday name 

%ob Abbreviated month name 

%B Full month name 

Joc Date and time representation appropriate for the locale 
%od Day of the month as a decimal number (01 — 31) 
%H Hour in 24-hour format (00 — 23) 

%l Hour in 12-hour format (01 — 12) 

%y} Day of the year as a decimal number (001 — 366) 
Jom Month as a decimal number (01 — 12) 

%M Minute as a decimal number (00 — 59) 


%op Current locale’s AM/PM indicator for a 12-hour clock 
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Return Value 


Compatibility 


See Also 


Example 


Format Description 

%S Second as a decimal number (00 — 59) 

%U Week of the year as a decimal number; with Sunday as the first day of 
the week (00 — 51) 

Tow Weekday as a decimal number (0 — 6; Sunday is 0) 

JoW Week of the year as a decimal number; with Monday as the first day of 
the week (00 — 51) 

Tox Date representation for current locale 

%X Time representation for current locale 

Toy Year without the century as a decimal number (00 — 99) 

JY Year with the century as a decimal number 

%oz, Time zone name or abbreviation; no characters if time zone is unknown 

TN Percent sign 


The strftime function returns the number of characters placed in string if the total 
number of resulting characters, including the terminating null, is not more than 
maxsize. 


Otherwise, strftime returns 0, and the contents of the string are indeterminate. 


Standards: ANSI 
16-Bit: DOS, QWIN, WIN 
32-Bit: DOS32X 


localeconv, setlocale, strcoll, strxfrm 


See the example for time. 


Description 


Remarks 


_Stricmp, _ fstricmp 759 


_Stricmp, _ fstricmp 


Perform a lowercase comparison of strings. 
#include <string.h> Required only for function declarations 


int _stricmp( const char *string/, const char *string2 ); 


int __ far _fstricmp( const char __ far *string/, const char __ far *string2 ); 


string I String to compare 


string2 String to compare 


The _stricmp and _fstricmp functions perform a lexicographical comparison of 
lowercase versions of string/ and string2 and return a value indicating their rela- 
tionship, as follows: 


Value Meaning 

<0 string! less than string2 

= 0 string I identical to string2 
> 0 string! greater than string2 


Note that two strings containing characters located between ’Z’ and ’a’ in the 
ASCII table ([’, ’’V,’]’,’”’, ’_’, and ’*’) compare differently depending on their 
case. For example, the two strings, "ABCDE" and "ABCD*", compare one way if 
the comparison is lowercase ("abcde" > “abcd*") and compare the other way 
("ABCDE" < "ABCD*") if it is Uppercase. 


The _stricmp and _ fstricmp functions operate on null-terminated strings. The 
string arguments to these functions are expected to contain a null character (’\0’) 
marking the end of the string. 


The _fstricmp function is a model-independent (large-model) form of the 
_stricmp function. The behavior and return value of _fstricmp are identical to 
those of the model-dependent function _stricmp, with the exception that the 
arguments are far pointers. 


The _strempi function is functionally equivalent to _stricmp. It is included in 
STRING.H for compatibility with eee versions of Microsoft C. The preferred 
form is _stricmp. 


The stremp function is a case-sensitive version of _ stricmp. 
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Return Value The return values for these functions are described above. 
Compatibility _stricmp 

Standards: None 

16-Bit: DOS, QWIN, WIN, WIN DLL 

32-Bit: DOS32X 

_{stricmp 


Standards: None 


16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: None 
See Also memcmp, _memicmp, strcat, strepy, strncat, strncmp, strncpy, _ strnicmp, 


strrchr, _ strset, strspn 


Example See the example for stremp. 


Description 


Remarks 


Return Value 


Compatibility 


strlen, _fstrlen 761 


Strien, _fstrlen 


Get the length of a string. 
#include <string.h> Required only for function declarations 


size_t strlen( const char *string ); 


size_t _fstrlen( const char __ far *string ); 


string Null-terminated string 


The strlen and _fstrlen functions return the length in bytes of string, not includ- 
ing the terminating null character (’\0’). 


The _fstrlen function is a model-independent (large-model) form of the strlen 
function. The behavior and return value of _fstrlen are identical to those of the 
model-dependent function strlen, with the exception that the argument is a far 
pointer. 


These functions return the string length. There is no error return. 


strlen 

Standards: ANSI, UNIX 

16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 

_fstrien 


Standards: None 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: None 
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Example /* STRLEN.C */ 
fHinclude <string.h> 
dHinclude <stdio.h> 
dEinclude <conio.h> 
#Finclude <dos.h> 


void main( void ) 

{ 
char buffer[61] = "How long am 1?"; 
int len; 


len = strlen( buffer ); 
printf( "'%s' is 4d characters long\n", buffer, len ); 


Output ‘How long am I?’ is 14 characters long 


_ Striwr, _ fstriwr 763 


_ Striwr, _ fstriwr 


Description Convert a string to lowercase. 


#include <string.h> Required only for function declarations 


char *_strlwr( char “string ); 


char __ far * __ far _fstrlwr( char __ far *string ); 


string String to be converted 


Remarks The _strlwr and _fstrlwr functions convert any uppercase letters in the given 
null-terminated string to lowercase. Other characters are not affected. 


The _fstrlwr function is a model-independent (large-model) form of the _strlwr 
function. The behavior and return value of _fstrlwr are identical to those of the 
model-dependent function _ strlwr, with the exception that the argument and 
return values are far pointers. 


Return Value These functions return a pointer to the converted string. There is no error return. 
Compatibility _strlwr 

Standards: None 

16-Bit: DOS, QWIN, WIN, WIN DLL 

32-Bit: DOS32X 

_fstrlwr 


Standards: None 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: None 


See Also _strupr 
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Example /* STRLWR.C: This program uses _striwr and _strupr to create 
* uppercase and lowercase copies of a mixed-case string. 
a / 


fHinclude <string.h> 
dHinclude <stdio.h> 


void main( void ) 


{ 
char stringL100] = "The String to End All Strings!"; 
char *copyl, *copy2; 
copyl = _strlwr( _strdup( string ) ); 
copy2 = _strupr( _strdup( string ) ); 
printf( "Mixed: %s\n", string ); 
printf( “Lower: %s\n", copyl ); 
printf( "Upper: %s\n", copy2 ); 

} 

Output Mixed: The String to End All Strings! 


Lower: the string to end all strings! 
Upper: THE STRING TO END ALL STRINGS! 


Description 


Remarks 


Return Value 


Compatibility 


See Also 
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strncat, _fstrncat 


Append characters of a string. 
#include <string.h> Required only for function declarations 
char “strncat( char *string/, const char *string2, size_t count ); 


char __ far * __ far _fstrncat( char __ far *string/, const char __ far *string2, 
size_t count )3 


string I Destination string 
string2 Source string 
count Number of characters appended 


The strneat and _fstrneat functions append, at most, the first count characters of 
string2 to string 1, terminate the resulting string with a null character (’\0’), and 
return a pointer to the concatenated string (string1). If count is greater than the 
length of string2, the length of string2 is used in place of count. 


The _fstrneat function is a model-independent (large-model) form of the strncat 
function. The behavior and return value of _ fstrncat are identical to those of the 
model-dependent function strncat, with the exception that all the pointer argu- 
ments and return values are far pointers. 


The return values for these functions are described above. 


strncat 

Standards: ANSI, UNIX 

16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 

_fstrneat 


Standards: None 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: None 


strcat, strcmp, strcpy, strncmp, strncpy, _strnicmp, strrchr, _ strset, strspn 
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Example 


Output 


sirncat, _ fstrncat 


/* STRNCAT.C */ 
#tinclude <string.h> 
d#Hinclude <stdio.h> 


void main( void ) 


{ 
char string[80] = "This is the initial string!"; 
char suffixl] = " extra text to add to the string..."; 
/* Combine strings with no more than 19 characters of suffix: 
printf( "Before: %4s\n", string ); 
strncat( string, suffix, 19 ); 
printf( "After: %s\n", string ); 
} 


Before: This is the initial string! 
After: This is the initial string! extra text to add 


* / 


Description 


Remarks 


Return Value 


Compatibility 
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strncmp, _ fstrncmp 


Compare characters of two strings. 
#include <string.h> Required only for function declarations 
int strnemp( const char *string/, const char *string2, size_t count ); 


int ___ far _fstrnemp( const char __ far *string/, const char __ far *string2, 
size_t count ); 


string 1 String to compare 
string2 String to compare 
count Number of characters compared 


The strnemp and _ fstrnemp functions lexicographically compare, at most, the 
first count characters of string/ and string2 and return a value indicating the rela- 
tionship between the substrings, as listed below: 


Value Meaning 

<0 string] less than string2 

=0 string 1 equivalent to string2 
> 0 string] greater than string2 


The _strnicmp function is a case-insensitive version of strncmp. 


The _fstrnemp function is a model-independent (large-model) form of the 
strncmp function. The behavior and return value of _fstrnemp are identical to 
those of the model-dependent function strnemp, with the exception that all the 
arguments and return values are far. 


The return values for these functions are described above. 


strncmp 
Standards: ANSI, UNIX 
16-Bit: DOS, QWIN, WIN, WIN DLL 


32-Bit: DOS32X 
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See Also 


Example 


strncmp, _ fstrncmp 


_fstrnemp 

Standards: None 

16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: None 


strcat, strcmp, strepy, strncat, strncpy, strrchr, _ strset, strspn 


/* STRNCMP.C x*/ 
#tinclude <string.h> 
#Hinclude <stdio.h> 


char stringl[] = "The quick brown dog jumps over the lazy fox"; 
char string2[ ] "The QUICK brown fox jumps over the lazy dog"; 


void main( void ) 
{ 
char tmp[2Q]; 
int result; 


printf( "Compare strings:\n\t\t%s\n\t\t%s\n\n", stringl, string2 


printf ( "Function:\tstrncmp (first 10 characters only)\n" ); 
result = strncmp( stringl, string2 , 10 ); 
if( result > @ ) 
strcpy( tmp, "greater than" ); 
else if( result < @ ) 
strcpy( tmp, "less than" ); 
else 
strcpy( tmp, “equal to" ); 
printf( "Result:\t\tString 1 is %s string 2\n\n", tmp ); 


printf( "Function:\t_strnicmp (first 10 characters only)\n" ); 
result = _strnicmp( stringl, string2, 10 ); 
if( result > @ ) 
strcepy( tmp, "greater than" ); 
else if( result < @ ) 
strepy( tmp, "less than" ); 
else 
strcpy( tmp, "equal to" ); 
printf( "Result:\t\tString 1 is %s string 2\n\n", tmp ); 
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Output Compare strings: 
The quick brown dog jumps over the lazy fox 
The QUICK brown fox jumps over the lazy dog 


Function: Strncmp (first 1@ characters only) 
Result: String 1 is greater than string 2 
Function: Strnicmp (first 1@ characters only) 


Result: String 1 is equal to string 2 
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sirncpy, _ fstrncpy 


Description Copy characters of one string to another. 
#include <string.h> Required only for function declarations 
char *strncpy( char *string/, const char *string2, size_t count ); 


char __ far * __ far _fstrnepy( char __ far *string/, const char __far *string2, 
size_t count ); 


string] Destination string 
string2 Source string 
count Number of characters copied 
Remarks The strnepy and _fstrnepy functions copy count characters of string2 to string! 


and return string]. If count is less than the length of string2, a null character (’\0’) 
is not appended automatically to the copied string. If count is greater than the 
length of string2, the string/ result is padded with null characters (’\0’) up to 
length count. 


Note that the behavior of strncepy and _fstrncpy is undefined if the address 
ranges of the source and destination strings overlap. 


The _fstrnepy function is a model-independent (large-model) form of the strnepy 
function. The behavior and return value of _fstrnepy are identical to those of the 
model-dependent function strnepy, with the exception that all the arguments and 
return values are far. 


Return Value The return values for these functions are described above. 
Compatibility strncpy 

Standards: ANSI, UNIX 

16-Bit: DOS, QWIN, WIN, WIN DLL 


32-Bit: DOS32X 
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_fstrncpy 
Standards: None 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: None 
See Also strcat, strcmp, strcpy, strncat, strncmp, _ strnicmp, strrchr, _ strset, strspn 


Example /* STRNCPY.C */ 
#Hinclude <string.h> 
#Hinclude <stdio.h> 


void main( void ) 


{ 
char stringL100] = "Cats are nice usually"; 
printf("Before: 4s\n", string ); 
strncpy( string, "Dogs", 4 ); 
strncpy( string + 9, "mean", 4 ); 
printf("After: %s\n", string ); 

I 

Output Before: Cats are nice usually 


After: Dogs are mean usually 
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Description 


Remarks 


Return Value 


_Strnicmp, _ fstrnicmp 


Compare characters of two strings without regard to case. 
#include <string.h> Required only for function declarations 
int _strnicmp( const char *string/, const char *string2, size_t count ); 


int __far _fstrnicmp( const char __ far *string/, const char __ far *string2, 
size_t count ); 


string 1 String to compare 
string2 String to compare 
count Number of characters compared 


The _strnicmp and _fstrnicmp functions lexicographically compare (without re- 
gard to case), at most, the first count characters of string/ and string2 and return a 
value indicating the relationship between the substrings, as listed below: 


Value Meaning 

<0 string] less than string2 

= 0) string! equivalent to string2 
>0 string] greater than string2 


The strncemp function is a case-sensitive version of _strnicmp. 


Note that two strings containing characters located between ’Z’ and ’a’ in the 
ASCII table ([’, ’V,’]’, ?%’, ’_’, and ’*’) compare differently depending on their 
case. For example, the two strings, "ABCDE" and “ABCD*", compare one way if 
the comparison is lowercase ("abcde" > "abcd*") and compare the other way 
("ABCDE" < "ABCD*") if it is uppercase. 


The _fstrnicmp function is a model-independent (large-model) form of the 
_Sstrnicmp function. The behavior and return value of _fstrnicmp are identical to 
those of the model-dependent function _strnicmp, with the exception that all the 
arguments and return values are far. 


The return values for these functions are described above. 


Compatibility 


See Also 


Example 


_Strnicmp, _ fstrnicmp 


_Strnicmp 


Standards: None 


16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 
_fstrnicmp 


Standards: None 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: None 


strcat, strcmp, strcepy, strncat, strnepy, strrchr, _ strset, strspn 


See the example for strncmp. 


173 
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Description 


Remarks 


Return Value 


Compatibility 


See Also 


_Strnset, _ fstrnset 


Initialize characters of a string to a given character. 
#include <string.h> Required only for function declarations 


char *_strnset( char “string, int c, size_t count ); 


char __ far * __ far _fstrnset( char __ far *string, int c, size_t count ); 


string String to be initialized 
C Character setting 
count Number of characters set 


The _strnset and _fstrnset functions set, at most, the first count characters of 
string to c (converted to char) and return a pointer to the altered string. If count is 
greater than the length of string, the length of string is used in place of count. 


The _ fstrnset function is a model-independent (large-model) form of the _strnset 
function. The behavior and return value of _ fstrnset are identical to those of the 
model-dependent function _ strnset, with the exception that all the arguments and 
return values are far. 


The return values for these functions are described above. 


_ strnset 


Standards: None 


16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 
_fstrnset 


Standards: None 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: None 


strcat, strcmp, strepy, _ strset 


Example 


Output 


_ Strnset, _ fstrnset 


/* STRNSET.C */ 
#Hinclude <string.h> 
#tinclude <stdio.h> 


void main( void ) 


{ 
char stringL15] = "This is a test"; 
/* Set not more than 4 characters of string to be *'s */ 
printf( "Before: %s\n", string ); 
_strnset( string, '*', 4 ); 
printf( "After: %s\n", string ); 
} 


Before: This is a test 
After: **** is a test 
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Description 


Remarks 


Return Value 


Compatibility 


See Also 


strpbrk, _ fstrpbrk 


Scan strings for characters in specified character sets. 
#include <string.h> Required only for function declarations 


char *strpbrk( const char *string/, const char *string2 ); 


char __ far * __ far _fstrpbrk( const char __ far “string 1, 
const char __ far *string2 ); 


string 1 Source string 


string2 Character set 


The strpbrk function finds the first occurrence in string/ of any character from 
string2. The terminating null character (’\0’) is not included in the search. 


The _fstrpbrk function is a model-independent (large-model) form of the 
strpbrk function. The behavior and return value of _fstrpbrk are identical to 
those of the model-dependent function strpbrk, with the exception that all the 
arguments and return values are far. 


These functions return a pointer to the first occurrence of any character from 
string2 in string]. A NULL return value indicates that the two string arguments 


_have no characters in common. 


strpbrk 

Standards: ANSI, UNIX 

16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 

_fstrpbrk 

Standards: None 

16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: None 


strchr, strrchr 


Example 


Output 


strpbrk, _ fstrpbrk 


/* STRPBRK.C */ 
#tinclude <string.h> 
d#Finclude <stdio.h> 


void main( void ) 


{ 
char string[100] = "The 3 men and 2 boys ate 5 pigs\n"; 
char *result; 
/* Return pointer to first ‘a’ or 'b" in “string” */ 
priatte “le: Bsn"... string 
result = strpbrk( string, "0123456789" ); 
Prinlre “2s: 2SN 5 Pest 3)s 
result = strpbrk( result, "@123456789" ); 
printf( "3: %s\n", result++ ); 
result = strpbrk( result, "0123456789" ); 
printf( "4: %s\n", result ); 
} 


1: The 3 men and 2 boys ate 5 pigs 
2: 3 men and 2 boys ate 5 pigs 
3: 2 boys ate 5 pigs 


4: 5 pigs 


777 


778 strrchr, _ fstrrehr 


Description 


Remarks 


Return Value 


Compatibility 


See Also 


Strrehr, _ fstrrehr 


Scan a string for the last occurrence of a character. 
#include <string.h> Required only for function declarations 


char *strrchr( const char *string, int c ); 


char __far * __ far _fstrrchr( const char __ far *string, int c ); 


string Searched string 


C Character to be located 


The strrehr function finds the last occurrence of c (converted to char) in string. 
The string’s terminating null character (’\0’) is included in the search. (Use strehr 
to find the first occurrence of c in string.) 


The _fstrrchr function is a model-independent (large-model) form of the strrchr 
function. The behavior and return value of _fstrrchr are identical to those of the 
model-dependent function strrehr, with the exception that all the pointer argu- 
ments and return values are far pointers. 


These functions return a pointer to the last occurrence of the character in the 
string. A NULL pointer is returned if the given character is not found. 


strrchr 

Standards: ANSI, UNIX 

16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 

_fstrrchr 


Standards: None 
16-Bit: DOS, QWIN, WIN, WIN DLL 


32-Bit: None 


strchr, strespn, strncat, strncmp, strnepy, _strnicmp, strpbrk, strspn 


Example 


Output 


strrehr, _ fstrrehr 


/* STRCHR.C: This program illustrates searching for a character with 
* Strchr (search forward) or strrchr (search backward). 
* / 


#Finclude <string.h> 
d#Finclude <stdio.h> 


ING: Ghee. es 
char stringL] = "The quick brown dog jumps over the lazy fox"; 
char fmtl[] = " 1 2 3 4 2 ae 


char fmt2[ ] 


"1234567890123456/7890123456/8901234567890123456/7890" ; 


void main( void ) 
{ 
char *pdest; 
int result; 


printf( "String to be searched: \n\t\t%s\n", string ); 
printfrc "\CATASANAt\tes nin”, fmtl,. fmtZ .)3 
printf( "Search char:\t%c\n", ch ); 


/* Search forward. */ 

pdest = strchr( string, ch ); 
result = pdest - string + 1; 
if( pdest != NULL ) 


printf( "Result:\tfirst %c found at position %4d\n\n", ch, result ); 


else 
printf( "Result:\t%c not found\n" ); 


/* Search backward. */ 
pdest = strrchr( string, ch ); 
result = pdest - string + 1; 
if( pdest != NULL ) 
printf( "Result:\tlast %c found at position %d\n\n", ch, result ); 
else 
printf( "Result:\t%c not found\n" ); 


String to be searched: 


The quick brown dog jumps over the lazy fox 
1 2 3 4 5 
1234567890123456789012345678901234567890123456/890 


Search char: F 
Result: first r found at position 12 


Result: last r found at position 30 
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780 _Strrev, _ fstrrev 


Description 


Remarks 


Return Value 


Compatibility 


See Also 


_ Strrev, _ fstrrev 


Reverse characters of a string. 
#include <string.h> Required only for function declarations 


char *_strrev( char *string ); 


char __ far * __ far _fstrrev( char __far *string ); 


string String to be reversed 


The _strrev function reverses the order of the characters in string. The terminat- 
ing null character (’\0’) remains in place. 


The _ fstrrev function is a model-independent (large-model) form of the _strrev 
function. The behavior and return value of _fstrrev are identical to those of the 
model-dependent function _strrev, with the exception that the argument and 
return value are far pointers. 


These functions return a pointer to the altered string. There is no error return. 


_Strrev 


Standards: None 


16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 
_fstrrev 


Standards: None 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: None 


strepy, _strset 


_Strrev, _ fstrrev 781 


Example /* STRREV.C: This program checks an input string to see whether it is a 
* palindrome: that is, whether it reads the same forward and backward. 
* / 


#Hinclude <string.h> 
#Hinclude <stdio.h> 


void main( void ) 


{ 
char string[100]; 
int result; 
printf( "Input a string and I will tell you if it is a palindrome:\n" ); 
gets( string ); 
/* Reverse string and compare (ignore case): */ 
result = _strcempi( string, _strrev( _strdup( string ) ) ); 
if( result == @ ) 
printf( "The string \"%s\" is a palindrome\n\n", string ); 
else 
printf( "The string \"%s\" is not a palindrome\n\n", string ); 
} 
Output Input a string and I will tell you if it is a palindrome: 


Able was I ere I saw Elba 
The string "Able was I ere I saw Elba" is a palindrome 


782 _Strset, _ fstrset 


Description 


Remarks 


Return Value 


Compatibility 


See Also 


_ Strset, _fstrset 


Set characters of a string to a character. 
#include <string.h> Required only for function declarations 


char *_strset( char *string, int c ); 


char __far * __ far _fstrset( char __ far *string, int c ); 


string String to be set 


C Character setting 


The _strset function sets all of the characters of string to c (converted to char), ex- 
cept the terminating null character (’\0’). 


The _fstrset function is a model-independent (large-model) form of the _ strset 
function. The behavior and return value of _fstrset are identical to those of the 
model-dependent function _strset, with the exception that the pointer arguments 
and return value are far pointers. 


These functions return a pointer to the altered string. There is no error return. 


_ Strset 


Standards: None 


16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 
_fstrset 


Standards: None 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: None 


memset, strcat, strcmp, strcpy, _ strnset 


Example 


Output 


_Strset, _ fstrset 


/* STRSET.C */ 
#Finclude <string.h> 
dFinclude <stdio.h> 


void main( void ) 


{ 
char stringL] = "Fill the string with something"; 
printf( "Before: %s\n", string ); 
_strset( string, ‘'*' ); 
DRIMGEE. KATbers, 2S \n" >. Siri: )s 
} 


Before: Fill the string with something 
After: 2 2K 2K 2 OS Ok 2 2K ik 2k Oe 2K 2k 2g OK 2K ok 2c OK 2K Og OK OE Oe OK OK OK OK OK ok 
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784 strspn, _ fstrspn 


Description 


Remarks 


Return Value 


Compatibility 


Strspn, _ fstrspn 


Find the first substring. 
#include <string.h> Required only for function declarations 


size_t strspn( const char *string/, const char *string2 ); 


size_t __ far _fstrspn( const char __ far *string/, const char __ far *string2 ); 


string] Searched string 


string2 Character set 


The strspn function returns the index of the first character in string / that does not 
belong to the set of characters specified by string2. This value is equivalent to the 
length of the initial substring of string/ that consists entirely of characters from 
string2. The null character (’\0’) terminating string2 is not considered in the 
matching process. If string/ begins with a character not in string2, strspn 

returns 0. 


The _ fstrspn function is a model-independent (large-model) form of the strspn 
function. The behavior and return value of _ fstrspn are identical to those of the 
model-dependent function strspn, with the exception that the arguments are far 
pointers. 


These functions return an integer value specifying the length of the segment in 
string] consisting entirely of characters in string2. 


strspn 
Standards: ANSI, UNIX 
16-Bit: DOS, QWIN, WIN, WIN DLL 


32-Bit: DOS32X 


See Also 


Example 


Output 


Strspn, _ fstrspn 785 


_fstrspn 

Standards: None 

16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: None 


strcspn, strncat, strncmp, strncpy, _strnicmp, strrchr 


/* STRSPN.C: This program uses strspn to determine the length of 

* the segment in the string "cabbage" consisting of a's, b's, and c's. 
* In other words, it finds the first non-abc letter. 

* / 


#Finclude <string.h> 
#Hinclude <stdio.h> 


void main( void ) 

{ 
char string[] = "cabbage"; 
int result; 


result = strspn( string, "abc" ); 
printf( "The portion of '%s' containing only a, b, orc 
"is 4d bytes long\n", string, result ); 


The portion of ‘cabbage’ containing only a, b, or c is 5 bytes long 


786 strstr, _ fstrstr 


Description 


Remarks 


Return Value 


Compatibility 


See Also 


Strstr, _ fstrstr 


Find a substring. 
#include <string.h> Required only for function declarations 


char *strstr( const char *string/, const char *string2 ); 


char __far * __ far _fstrstr( const char __ far *string/, 
const char __ far *string2 ); 


string] Searched string 


string2 String to search for 


The strstr function returns a pointer to the first occurrence of string2 in string. 


The _fstrstr function is a model-independent (large-model) form of the strstr 
function. The behavior and return value of _ fstrstr are identical to those of the 
model-dependent function strstr, with the exception that the arguments and return 
value are far pointers. 


These functions return either a pointer to the first occurrence of string2 in string /, 
or NULL if they do not find the string. 


strstr 

Standards: ANSI 

16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 

_fstrstr 


Standards: None 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: None 


strcspn, strncat, strncmp, strncpy, _strnicmp, strpbrk, strrchr, strspn 


Strstr, _fstrstr 


Example /* STRSTR.C */ 
#Finclude <string.h> 
d#Einclude <stdio.h> 


char str[] = "lazy"; 
char stringL] = "The quick brown dog jumps over the lazy fox"; 
char fmt1l[] = " 1 2 3 4 oe 
char fmt2[] = "123456789012345678901234567890123456/78901234567890"; 
void main( void ) 
{ 

char *pdest; 

int result; 

printf( "String to be searched:\n\t%s\n", string ); 

printf( "\t%s\n\t%s\n\n", fmtl, fmt2 ); 

pdest. = sStrstr(- string, str: Js 

result = pdest - string + 1; 

if( pdest != NULL ) 

printf( "%s found at position %d\n\n", str, result ); 
else 
printf( "%s not found\n", str ); 
} 
Output String to be searched: 
The quick brown dog jumps over the lazy fox 
1 2 3 4 5 


123456789012345678901234567890123456/890123456/890 


lazy found at position 36 
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788 _ Strtime 


Description 


Remarks 


Return Value 


Compatibility 


See Also 


_ strtime 


Copies the time to a buffer. 
#include <time.h> 
char *_strtime( char “timestr ); 


timestr Time string 


The _strtime function copies the current time into the buffer pointed to by 
timestr. The time is formatted as 


hh:mm:ss 
where hh is two digits representing the hour in 24-hour notation, mm is two digits 


representing the minutes past the hour, and ss is two digits representing seconds. 
For example, the string 


18:23:44 
represents 23 minutes and 44 seconds past 6:00 PM. 
The buffer must be at least nine bytes long. 


The _strtime function returns a pointer to the resulting text string timestr. 


Standards: None 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 


asctime, ctime, gmtime, localtime, mktime, time, _ tzset 


_ $trtime 789 


Example /* STRTIME.C */ 
d##include <time.h> 
dAinclude <stdio.h> 


void main( void ) 

{ 
char dbuffer [9]; 
char tbuffer [9]; 


_strdate( dbuffer ); 
printf( "The current date is 4s \n", dbuffer ); 
_strtime( tbuffer ); 
printf( "The current time is %s \n", tbuffer ); 


Output The current date is 06/20/99 
The current time is 09:33:13 


790 strtod, strtol, _strtold, strtoul 


Description 


Remarks 


Strtod, strtol, _strtold, strtoul 


Convert strings to a double-precision (strtod), long-double-precision (_strtold), 
long-integer (strtol), or unsigned long-integer (strtoul) value. 


#include <stdlib.h> 


double strtod( const char *nptr, char **endptr ); 
long strtol( const char *nptr, char **endptr, int base ); 
long double _strtold( const char *nptr, char **endptr ); 


unsigned long strtoul( const char *nptr, char **endptr, int base ); 


nptr String to convert 
endptr Pointer to character that stops scan 
base Number base to use 


The strtod, _strtold, strtol, and strtoul functions convert a character string to a 

double-precision value, a long-double value, a long-integer value, or an unsigned 
long-integer value, respectively. The input string is a sequence of characters that 

can be interpreted as a numerical value of the specified type. 


These functions stop reading the string at the first character they cannot recognize 
as part of a number. This may be the null character (’\0’) at the end of the string. 
With strtol or strtoul, this terminating character can also be the first numeric char- 
acter greater than or equal to base. If endptr is not NULL, a pointer to the charac- 
ter that stopped the scan is stored at the location pointed to by endptr. If no 
conversion could be performed (no valid digits were found or an invalid base was 
specified), the value of nptr is stored at the location pointed to by endptr. 


The strtod and _strtold functions expect nptr to point to a string with the 
following form: 


[[whitespace ]] |[sign] [digits] [|.digits] [| {d | D1e| E}[[sign]|digits]] 


A whitespace consists of space and tab characters, which are ignored; sign is 
either plus (+) or minus (—); and digits are one or more decimal digits. If no digits 
appear before the decimal point, at least one must appear after the decimal point. 
The decimal digits can be followed by an exponent, which consists of an intro- 
ductory letter (b, D, e, or E) and an optionally signed decimal integer. 


Return Value 


Compatibility 


strtod, strtol, _strtold, strtoul 791 


The first character that does not fit this form stops the scan. 

The strtol function expects nptr to point to a string with the following form: 
[whitespace] [sign] [0] [{ x |X }]] [digits] 

The strtoul function expects nptr to point to a string having this form: 
[whitespace] [l{ +!-}] (00 [{ x! X }]] [digits] 


If base is between 2 and 36, then it is used as the base of the number. If base is 0, 
the initial characters of the string pointed to by nptr are used to determine the base. 
If the first character 1s 0 and the second character is not ’x’ or ’X’, then the string 
is interpreted as an octal integer; otherwise, it is interpreted as a decimal number. 
If the first character is ’0’ and the second character is ’x’ or ’X’, then the string is 
interpreted as a hexadecimal integer. If the first character is ’1’ through ’9’, then 
the string is interpreted as a decimal integer. The letters ’a’ through ’z’ (or ’A’ 
through ’Z’) are assigned the values 10 through 35; only letters whose assigned 
values are less than base are permitted. 


The strtoul function allows a plus (+) or minus (—) sign prefix; a leading minus 
sign indicates that the return value is negated. 


The strtod and _strtold functions return the value of the floating-point number, 
except when the representation would cause an overflow, in which case they re- 
turn + HUGE_VAL. The functions return 0 if no conversion could be performed 
or an underflow occurred. 


The strtol function returns the value represented in the string, except when the 
representation would cause an overflow, in which case it returns LONG_ MAX or 
LONG_MIN. The function returns 0 if no conversion could be performed. 


The strtoul function returns the converted value, if any. If no conversion can be 
performed, the function returns 0. The function returns ULONG_ MAX on 
overflow. 


In all four functions, errno is set to ERANGE if overflow or underflow occurs. 


strtod, strtol 

Standards: ANSI, UNIX 

16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 


792 Strtod, strtol, _strtold, strtoul 


_Strtold 
Standards: None 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: None 
strtoul 
Standards: ANSI 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 
See Also | atof, atol 


Example /* STRTOD.C: This program uses strtod to convert a string to a 
* double-precision value; strtol to convert a string to long 
* integer values; and strtoul to convert a string to unsigned 
* lJong-integer values. 
* / 


d4einclude <stdlib.h> 
#Hinclude <stdio.h> 


void main( void ) 


{ 
char *String, *stopstring; 
double x; 
long I 
int base; 


unsigned long ul; 


string = "3.1415926This stopped it"; 

xX = Strtod( string, &stopstring ); 

printf( "string = %s\n", string ); 

printf(" strtod = 4f\n", x ); 

printf(" Stopped scan at: %s\n\n", stopstring ); 


String = "-10110134932This stopped it"; 

1 = strtol( string, &stopstring, 10 ); 

printf( “string = 4s\n", string ); 

printf(" strtol = 41ld\n", 1 ); 

DrInere Stopped scan at: %s\n\n", stopstring ); 


Output 


strtod, strtol, _strtold, strtoul 


string = "10110134932"; 
printf( "string = %s\n", string ); 
/* Convert string using base 2, 4, and 8: */ 
for( base = 2; base <= 8; base *= 2 ) 
{ 
/* Convert the string: */ 
ul = strtoul( string, &stopstring, base ); 
printf( " strtol = 41d (base 4d)\n", ul, base ); 
print." Stopped scan at: %s\n", stopstring ); 


String = 3.1415926This stopped it 
strtod = 3.141593 
Stopped scan at: This stopped it 


String = -10110134932This stopped it 
strtol = -2147483647 
Stopped scan at: This stopped it 


String = 10110134932 
strtol = 45 (base 2) 
Stopped scan at: 34932 
strtol = 4423 (base 4) 
Stopped scan at: 4932 
strtol = 2134108 (base 8) 
Stopped scan at: 932 
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794 strtok, _ fstrtok 


Description 


Remarks 


Return Value 


Strtok, _ fstrtok 


Find the next token in a string. 
#include <string.h> Required only for function declarations 


char *strtok( char *string/, const char *string2 ); 


char __far * __ far _fstrtok( char __ far *string/, const char __far *string2 ); 


string 1 String containing token(s) 


string2 Set of delimiter characters 


The strtok function reads string/ as a series of zero or more tokens and string2 as 
the set of characters serving as delimiters of the tokens in string]. The tokens in 
string] may be separated by one or more of the delimiters from string2. 


The tokens can be broken out of string/ by a series of calls to strtok. In the first 
call to strtok for string/, strtok searches for the first token in string/, skipping 
leading delimiters. A pointer to the first token is returned. To read the next token 
from string /, call strtok with a NULL value for the string/ argument. The NULL 
string] argument causes strtok to search for the next token in the previous token 
string. The set of delimiters may vary from call to call, so string2 can take any 
value. 


The _fstrtok function is a model-independent (large-model) form of the strtok 
function. The behavior and return value of _fstrtok are identical to those of the 
model-dependent function strtok, with the exception that the arguments and return 
value are far pointers. 


Note that calls to these functions will modify string/, since each time strtok is 
called it inserts a null character (’\0’) after the token in string/. 


The first time strtok is called, it returns a pointer to the first token in string/. In 
later calls with the same token string, strtok returns a pointer to the next token in 
the string. A NULL pointer is returned when there are no more tokens. All tokens 
are null-terminated. 


strtok, _ fstrtok 795 


Compatibility strtok 
Standards: ANSI, UNIX 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 
_fstrtok 
Standards: None 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: None 
See Also strcspn, strspn 


Example /* STRTOK.C: In this program, a loop uses strtok to print all the tokens 
* (Separated by commas or blanks) in the string named “string”. 
* / 


#Hinclude <string.h> 
4FAinclude <stdio.h> 


char stringL] = "A string\tof ,,tokens\nand some more tokens"; 
char sepsL] NEMS 
char *token; 


void main( void ) 
{ 
printf( "%s\n\nTokens:\n", string ); 


/* Establish string and get the first token: */ 
token = strtok( string, seps ); 
while( token != NULL ) 


{ 
/* While there are tokens in "string" */ 
printf( " %s\n", token ); 
/* Get next token: */ 
token = strtok( NULL, seps ); 
} 


796 strtok, _ fstrtok 


Output A string of ,,tokens 
and some more tokens 


Tokens: 
A 
string 
of 
tokens 
and 
some 
more 
tokens 


Description 


Remarks 


Return Value 


Compatibility 


See Also 


_Strupr, _ fstrupr 797 


_ Strupr, _ fstrupr 


Convert a string to uppercase. 
#include <string.h> Required only for function declarations 


char *_strupr( char “string ); 


char __ far * __ far _fstrupr( char __ far *string ); 


string String to be capitalized 


These functions convert any lowercase letters in the string to uppercase. Other 
characters are not affected. 


The _fstrupr function is a model-independent (large-model) form of the _ strupr 
function. The behavior and return value of _fstrupr are identical to those of the 
model-dependent function _ strupr, with the exception that the argument and 
return value are far pointers. 


These functions return a pointer to the converted string. There is no error return. 


_strupr 


Standards: None 


16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 

_fstrupr 

Standards: None 

16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: None 

_Sstrlwr 
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Example /* STRLWR.C: This program uses _strlwr and _strupr to create 
* uppercase and lowercase copies of a mixed-case string. 
* / 


#Hinclude <string.h> 
fHinclude <stdio.h> 


void main( void ) 


{ 
char string[100] = "The String to End All Strings!"; 
char *copyl, *copy2; 
copyl = _strlwr( _strdup( string ) ); 
copy2 = _strupr( _strdup( string ) ); 
printf( "Mixed: %s\n", string ); 
printf( "Lower: %s\n", copyl ); 
printf( "Upper: %s\n", copy2 ); 

} 

Output Mixed: The String to End All Strings! 


Lower: the string to end all strings! 
Upper: THE STRING TO END ALL STRINGS! 


Description 


Remarks 


Return Value 


strxfrm 799 
sirxtrm 
Transforms a string based on locale-specific information. 
#include <string.h> Required only for function declarations 


size_t strxfrm( char *string/, const char *string2, size_t count ); 


string 1 String to which transformed version of string2 is 
returned 

string2 String to transform 

count Maximum number of characters to be placed in 
string 1 


The strxfrm function transforms the string pointed to by string2 into a new col- 
lated form that is stored in string]. No more than count characters (including the 
null character) are transformed and placed into the resulting string. 


The transformation is made using the locale-specific information set by the 
setlocale function. 


After the transformation, a call to stremp with the two transformed strings will 
yield identical results to a call to strcoll applied to the original two strings. 


The value of the following expression is the size of the array needed to hold the 
transformation of the source string: 


1 + strxfrm( NULL, string, @ ) 


Currently, the run-time library supports the "C" locale only; thus strxfrm is 
equivalent to the following: 


strncpy( _stringl, _string2, _count ); 
return( strlen( _string2 ) ); 


The strxfrm function returns the length of the transformed string, not counting the 
terminating null character. If the return value is greater than or equal to count, the 
contents of string/ are unpredictable. 


— 800~—sStrxfrm 


Compatibility Standards: ANSI 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 


See Also localeconv, setlocale, stremp, strncmp, strcoll 


Description 


Remarks 


_ swab 801 
_ swab 
Swaps bytes. 
#include <stdlib.h> Required only for function declarations 


void _swab( char *src, char *dest, int n ); 


STC Data to be copied and swapped 
dest Storage location for swapped data 
n Number of bytes to be copied and swapped 


The _swab function copies n bytes from src, swaps each pair of adjacent bytes, 
and stores the result at dest. The integer n should be an even number to allow for 
swapping. The _swab function is typically used to prepare binary data for transfer 
to a machine that uses a different byte order. 


Return Value None. 

Compatibility Standards: UNIX 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 


Example 


Use _swab for compatibility with ANSI naming conventions of non-ANSI func- 
tions. Use swab and link with OLDNAMES.LIB for UNIX compatibility. 


/* SWAB.C */ 
dtinclude <stdlib.h> 
4Ainclude <stdio.h> 


char from[] = "BADCFEHGJILKNMPORQTSVUXWZY"; 
char tol] = Ia ia eat eh wah tear Ad te far ENG too: nl aA es ae 


void main( void ) 
{ 
printf( "Before:\t%s\n\t%s\n\n", from, to ); 
_swab( from, to, sizeof( from ) ); 
printf( “After:\t%s\n\t%s\n\n", from, to ); 
} 


s02 _swab 


Output Before: BADCFEHGJILKNMPORQTSVUXWZY 


eeoe3eoe3eeeeee ee ef ee ee ee ee 8 © oe 


After: BADCFEHGJILKNMPORQTSVUXWZY 
ABCDEFGHIJKLMNOPQRSTUVWXYZ 


Description 


Remarks 


Return Value 


system 803 


system 


Executes a command. 


#include <process.h> Required only for function declarations 
#include <stdlib.h> Use STDLIB.H for ANSI compatibility 


int system( const char *command ); 


command Command to be executed 


The system function passes command to the command interpreter, which executes 
the string as an operating-system command. The system function refers to the 
COMSPEC and PATH environment variables that locate the command-interpreter 
file (the file named COMMAND.COM in DOS). If command 1s a pointer to an 
empty string, the function simply checks to see whether or not the command inter- 
preter exists. 


If command is NULL and the command interpreter is found, the function returns a 
nonzero value. If the command interpreter is not found, it returns the value 0 and 
sets errno to ENOENT. If command is not NULL, the system function returns 
the value O if the command interpreter is successfully started. 


A return value of —1 indicates an error, and errno is set to one of the following 
values: 


Value Meaning 

E2BIG In DOS, the argument list exceeds 128 bytes, or the space required 
for the environment information exceeds 32K. 

ENOENT The command interpreter cannot be found. 

ENOEXEC The command-interpreter file has an invalid format and is not 
executable. 

ENOMEM Not enough memory is available to execute the command; or the 


available memory has been corrupted; or an invalid block exists, 
indicating that the process making the call was not allocated properly. 


804 system 


Compatibility 


See Also 


Example 


Standards: ANSI, UNIX 
16-Bit: DOS 
32-Bit: | DOS32X 


_exec functions, exit, _ exit, _ spawn functions 


/* SYSTEM.C: This program uses system to TYPE its source file. 


#Hinclude <process.h> 


Output 


void main( void ) 
{ 

system( "type system.c" ); 
} 


/* SYSTEM.C: This program uses system to TYPE its source file. 


#Hinclude <process.h> 


void main( void ) 
{ 
system( "type system.c" ); 


4S 


* / 


* / 


Description 


Remarks 


Return Value 


tan Functions 805 


tan Functions 


Calculate the tangent (tan and _tanl) and hyperbolic tangent (tanh and _ tanhl). 
#include <math.h> 


double tan( double x ); 
double tanh( double x ); 
long double _tanl( long double x ); 


long double _ tanhl( long double x ); 


x Angle in radians 


The tan functions return the tangent or hyperbolic tangent of their arguments. The 
list below describes the differences between the various tangent functions: 


Function Description 

tan Calculates tangent of x 

tanh Calculates hyperbolic tangent of x 

_tanl Calculates tangent of x (80-bit version) 

_tanhl Calculates hyperbolic tangent of x (80-bit version) 


The _ tanl and _ tanhl functions are the 80-bit counterparts and use an 80-bit, 10- 
byte coprocessor form of arguments and return values. See the reference page on 
the long double functions for more details on this data type. 


The tan function returns the tangent of x. If x is large, a partial loss of significance 
in the result may occur; in this case, tan sets errno to ERANGE and generates a 
_PLOSS error. If x is so large that significance is totally lost, tan prints a 

_ TLOSS error message to stderr, sets errno to ERANGE, and returns 0. Error 
handling can be modified by using the _matherr function. 


There is no error return for tanh. 


tan Functions 


tan, tanh 

Standards: ANSI, UNIX 

16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 


_tanl, _ tanhl 


Standards: None 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: None 


acos functions, asin functions, atan functions, cos functions, sin functions 


/* TAN.C: This program displays the tangent of pi / 4 and the hyperbolic 


* tangent of the result. 


d#Finclude <math.h> 
dAinclude <stdio.h> 


void main( void ) 


806 
Compatibility 
See Also 
Example 
{ 
j 
Output 


double pi = 3.1415926535; 
double x, y; 


tan( pi / 4 ); 


y = tanh( x ); 
printf( “tan( 4f ) = 4f\n", x, y ); 
printf( “tanh( “2f ) = “4f\n", y, x ); 


tan( 1.000000 ) = 0.761594 
tanh( @.761594 ) = 1.000000 


Description 


Remarks 


Return Value 


Compatibility 


See Also 


Example 


_ tell 807 


_ tell 


Gets the position of the file pointer. 
#include <io.h> Required only for function declarations 
long _ tell( int handle ); 


handle Handle referring to open file 


The _ tell function gets the current position of the file pointer (if any) associated 
with the handle argument. The position is expressed as the number of bytes from 
the beginning of the file. 


A return value of —1L indicates an error, and errno is set to EBADF to indicate an 
invalid file-handle argument. On devices incapable of seeking, the return value is 
undefined. 


Standards: None 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 


ftell, _ lseek 


/* TELL.C: This program uses _tell to tell the file pointer position 
* after a file read. 


dFinclude <io.h> 
dFinclude <stdio.h> 
deinclude <fcntl.h> 
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void main( void ) 

{ 
int fh; 
long position; 
char buffer[500]; 


if( (fh = _open( "tell.c", _O_RDONLY )) != -1 ) 
{ 
if( _read( fh, buffer, 500 ) > @ ) 
printf( "Current file position is: %d\n", _tell( fh ) ); 


_close( fh ); 


Output Current file position is: 425 


Description 


Remarks 
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_tempnam, tmpnam 
Create temporary filenames. 
#include <stdio.h> 


char *_tempnam( char *dir, char *prefix ); 


char *tmpnam( char “string ); 


string Pointer to temporary name 
dir Target directory to be used if TMP not defined 
prefix Filename prefix 


The tmpnam function generates a temporary filename that can be used to open a 
temporary file without overwriting an existing file. This name is stored in string. If 
string is NULL, then tmpnam leaves the result in an internal static buffer. Thus, 
any subsequent calls destroy this value. If string is not NULL, it is assumed to 
point to an array of at least L_tmpnam bytes (the value of L_ tmpnam is defined 
in STDIO.H). The function will generate unique filenames for up to TMP_MAX 
calls. 


The character string that tmpnam creates consists of the path prefix, defined by 
the entry P_tmpdir in the file STDIO.H, followed by a sequence consisting of 
the digit characters ’0’ through 9’; the numerical value of this string can range 
from | to 65,535. Changing the definitions of L_tmpnam or P_tmpdir in 
STDIO.H does not change the operation of tmpnam. 


The _tempnam function allows the program to create a temporary filename for 
use in another directory. This filename will be different from that of any existing 
file. The prefix argument is the prefix to the filename. The _ tempnam function 
uses malloc to allocate space for the filename; the program is responsible for free- 
ing this space when it is no longer needed. The _ tempnam function looks for the 
file with the given name in the following directories, listed in order of precedence: 


Directory Used Conditions 

Directory specified by TMP TMP environment variable is set, and directory 
specified by TMP exists. | 

dir argument to _tempnam TMP environment variable is not set, or 


directory specified by TMP does not exist. 
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Directory Used Conditions 


P_tmpdir in STDIO.H The dir argument is NULL, or dir is name of 
nonexistent directory. 


Current working directory P_tmpdir does not exist. 


If the search through the locations listed above fails, _ tempnam returns the value 
» NULL. 


Return Value The tmpnam and _ tempnam functions both return a pointer to the name 
generated, unless it is impossible to create this name or the name is not unique. If 
the name cannot be created or if a file with that name already exists, tmpnam and 
_tempnam return the value NULL. 


Compatibility _tempnam 
Standards: UNIX 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 


Use _tempnam for compatibility with ANSI naming conventions of non-ANSI 
functions. Use tempnam and link with OLDNAMES.LIB for UNIX compatibility. 


tmpnam 
Standards: ANSI, UNIX 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 
See Also tmpfile 


Example /* TEMPNAM.C: This program uses tmpnam to create a unique filename in 
* the current working directory, then uses _tempnam to create a unique 
* filename with a prefix of stq. 
« / 


d#Hinclude <stdio.h> 
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void main( void ) 


{ 
char *namel, *name2; 
/* Create a temporary filename for the current working directory: */ 
if( ¢€ namel = tmpnam( NULL ) ) != NULL ) 
printf( "%s is safe to use as a temporary file.\n", namel ); 
else 
printf( "Cannot create a unique filename\n" ); 
/* Create a temporary file name in temporary directory with the 
* prefix "stq". The actual destination directory may vary depending 
* on the state of the TMP environment variable and the global variable 
* P_tmpdir. 
* / 
if( ( name2 = _tempnam( “"c:\\tmp", “stq™ ) ) != NULL ) 
printf( "%s is safe to use as a temporary file.\n", name2 ); 
else 
printf( "Cannot create a unique filename\n" ); 
} 
Output \2 is safe to use as a temporary file. 


C:\TMP\stq2 is safe to use as a temporary file. 


812. ~—sttime 
time 

Description Gets the system time. 
#include <time.h> Required only for function declarations 
time_t time( time_t *timer ); 


timer Storage location for time 


Remarks The time function returns the number of seconds elapsed since midnight 
(00:00:00), December 31, 1899, Universal Coordinated Time, according to the 
system clock. The system time is adjusted according to the _ timezone system 
variable, which is explained under _ tzset. 


The return value is stored in the location given by timer. This parameter may be 
NULL, in which case the return value is not stored. 


Return Value The time function returns the time in elapsed seconds. There is no error return. 
Compatibility Standards: ANSI, UNIX 

16-Bit: DOS, QWIN, WIN, WIN DLL 

32-Bit: DOS32X 


See Also asctime, _ ftime, gmtime, localtime, _ tzset, _ utime 


Example 


/* TIMES.C illustrates various time and date functions including: 


* 
* 
* 
* 


time _ftime ctime asctime 
localtime gmtime mktime _tzset 
_strtime _strdate strftime 


* Also the global variable: 


* 


* / 


_tzname 


4#tinclude <time.h> 
#Hinclude <stdio.h> 
#Hinclude <sys\types.h> 
dinclude <sys\timeb.h> 
#tinclude <string.h> 


void main( void ) 


{ 


char tmpbuf[128], ampm[] = "AM"; 

time_t |ltime; 

struct _timeb tstruct; 

struct tm *today, *gmt, xmas = { 0, @, 12, 25, 11, 91 }; 


/* Set time zone from TZ environment variable. If TZ is not set 
* PST8PDT is used (Pacific standard time, daylight savings). 
* / 

_tzset(); 


/* Display DOS-style date and time. */ 
_strtime( tmpbuf ); 

printf( "DOS time:\t\t\t\t%s\n", tmpbuf ); 
_strdate( tmpbuf ); 

printf( "DOS date:\t\t\t\t%s\n", tmpbuf ); 


/* Get UNIX-style time and display as number and string. */ 
time( &ltime ); 

printf( "Time in seconds since GMT 1/1/70@:\t%ld\n", Iltime ); 
printf( "UNIX time and date:\t\t\t%s", ctime( &ltime ) ); 


/* Display GMT. */ 
gmt = gmtime( &ltime ); 
printf( "Greenwich Mean Time:\t\t\t%s", asctime( gmt ) ); 


/* Convert to time structure and adjust for PM if necessary. */ 
today = localtime( &ltime ); 
if( today-tm_hour 12 ) 
{ 
strcpy( ampm, "PM" ); 
today-tm_hour -= 12; 


time 


’ 


813 


814 


Output 


time 


/* Note how pointer addition is used to skip the first 11 characters 
* and printf is used to trim off terminating characters. 
* / 
printf( "12-hour time: \t\t\t\t%.8s Z%s\n", 
asctime( today ) + 11, ampm ); 


/* Print additional time information. */ 

ftime( &tstruct ); 

printf( "Plus milliseconds:\t\t\t%u\n", tstruct.millitm ); 

printf( "Zone difference in seconds from GMT:\tZu\n", tstruct.timezone ); 
printf( "Time zone name:\t\t\t\t%s\n", tznamelQ] ); 

printf( "Daylight savings:\t\t\t%s\n", tstruct.dstflag ? "YES" : "NO" ); 


/* Make time for noon on Christmas, 1991. */ 
if( mktime( &xmas ) != (time_t)-1 ) 
printf( "Christmas\t\t\t\t%s\n", asctime( &xmas ) ); 


/* Use time structure to build a customized time string. */ 
today = localtime( &ltime ); 


/* Use strftime to build a customized time string. */ 
strftime( tmpbuf, 128, 

"Today is ZA, day %d of 4B in the year %Y.\n", today ); 
printf( tmpbuf ); 


} 

DOS time: 17:36:10 

DOS date: 12/15/99 

Time in seconds since GMI 1/1/70: -1398750726 

UNIX time and date: Wed Dec 15 17:36:10 1999 
Greenwich Mean Time: Thu Dec 16 00:36:10 1999 
12-hour time: 05:36:10 PM 

Plus milliseconds: 90 

Zone difference in seconds from GMT: 480 

Time zone name: PST 

Daylight savings: NO 

Christmas Wed Dec 25 12:00:00 1999 


Today is Wednesday, day 15 of December in the year 1999. 


Description 


Remarks 


Return Value 


Compatibility 


See Also 


Example 
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tmpfile 


Creates a temporary file. 
#include <stdio.h> 


FILE *tmpfile( void ); 


The tmpfile function creates a temporary file and returns a pointer to that stream. 
If the file cannot be opened, tmpfile returns a NULL pointer. 


This temporary file is automatically deleted when the file is closed, when the pro- 
gram terminates normally, or when __rmtmp is called, assuming that the current 
working directory does not change. The temporary file is opened in w+b (binary 
read/write) mode. 


If successful, the tmpfile function returns a stream pointer. Otherwise, it returns a 
NULL pointer. 


Standards: ANSI, UNIX 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 


_rmtmp, _tempnam, tmpnam 


/* TMPFILE.C: This program uses tmpfile to create a temporary file, 
* then deletes this file with _rmtmp. 


d4Ainclude <stdio.h> 
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void main( void ) 


{ 
FILE *stream; 
char tempstring[] = "String to be written"; 
int i; 
/* Create temporary files. */ 
for(. 1 = 1s 1 <= 10; i++ ) 
{ 
if( (stream = tmpfile()) == NULL ) 
perror( “Could not open new temporary file\n" ); 
else 
printf( "Temporary file %d was created\n", i ); 
} 
/* Remove temporary files. */ 
printf( "%d temporary files deleted\n", _rmtmp() ); 
} 
Output Temporary file 1 was created 


1 

Temporary file 2 was created 
Temporary file 3 was created 
Temporary file 4 was created 

Temporary file 5 was created 

Temporary file 6 was created 

Temporary file 7 was created 

Temporary file 8 was created 

Temporary file 9 was created 

Temporary file 1@ was created 
1@ temporary files deleted 


Description 


Remarks 
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__toascii, tolower, toupper Functions 


Convert characters. 


#include <ctype.h> 


int __ toascii( int c ); 


int tolower( int c ); 


int _ tolower( int c ); 


int toupper( int c ); 


int _toupper‘( int c ); 


Character to be converted 


The __ toascii, tolower, _ tolower, toupper, and _ toupper routines and their 
associated macros convert a single character, as described below: 


Function 


__ toascii 
tolower 
_tolower 
toupper 
_toupper 


Macro 


__ toascii 
tolower 
_tolower 
toupper 
_toupper 


Description 


Converts c to ASCII character 
Converts c to lowercase if appropriate 
Converts c to lowercase 

Converts c to uppercase if appropriate 
Converts c to uppercase 


The __ toascii routine sets all but the low-order 7 bits of c to 0, so that the con- 
verted value represents a character in the ASCII character set. If c already repre- 
sents an ASCII character, c is unchanged. 


The tolower routine converts c to lowercase if c represents an uppercase letter. 


Otherwise, c is unchanged. 


The _ tolower routine is a version of tolower to be used only when c is known to 
be uppercase. The result of _ tolower is undefined if c is not an uppercase letter. 


The toupper routine convers c to uppercase if c represents an lowercase letter. 


Otherwise, c is unchanged. 
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Return Value 


The _toupper routine is a version of toupper to be used only when c is known to 
be lowercase. The result of _ toupper is undefined if c is not a lowercase letter. 


These routines are implemented both as functions and as macros. To conform to 
the ANSI specification, the tolower and toupper routines are also implemented as 
functions. The function versions can be used by removing the macro definitions 
through #undef directives or by not including CTYPE.H. Function declarations of 
tolower and toupper are given in STDLIB.H. 


If the /Za compile option is used, the macro form of toupper or tolower is not 
used because it evaluates its argument more than once. Since the arguments are 
evaluated more than once, arguments with side effects would produce potentially 
bad results. 


The __ toascii, tolower, _ tolower, toupper, and _ toupper routines return the 
converted character c. There is no error return. 


Compatibility __toascii, _tolower, _ toupper 


See Also 


Example 


Standards: UNIX 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 


Use __ toascii for compatibility with ANSI naming conventions of non-ANSI 
functions. Use toascii and link with OLDNAMES.LIB for UNIX compatibility. 


tolower, toupper 


Standards: ANSI, UNIX 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 


is functions 


/* TOUPPER.C: This program uses toupper and tolower to analyze all 

* characters between @x@ and @x7F. It also applies _toupper and _tolower 
* to any code in this range for which these functions make sense. 

** / 


#Finclude <conio.h> 
#Finclude <ctype.h> 
#Hinclude <string.h> 


char msgL] = "Some of THESE letters are Capitals\r\n"; 
char *p; 
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void main( void ) 


{ 
_cputs( msg ); 
/* Reverse case of message. */ 
for( p = msg; p < msg + strlen( msg ); ptt ) 
{ 
if( islower( *p ) ) 
_putch( _toupper( *p ) ); 
else if( isupper( *p ) ) 
_putch( _tolower( *p ) ); 
else 
_putch( *p ); 
F 
} 
Output Some of THESE letters are Capitals 


SOME OF these LETTERS ARE cAPITALS 
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820 _ tzset 


Description 


Remarks 


_tzset 


Sets time environment variables. 
#include <time.h> Required only for function declarations 
void _ tzset( void ); 


int _ daylight Global variables set by function 
long _ timezone | 
char *_tzname[2] 


The _ tzset function uses the current setting of the environment variable TZ to as- 
sign values to three global variables: _ daylight, _ timezone, and _ tzname. These 
variables are used by the _ ftime and localtime functions to make corrections from 
Universal Coordinated Time (UCT) to local time, and by time to compute UCT 
from system time. 


Use the following syntax to set the TZ environment variable: 
set TZ=tzn|[+ | —hhl[:mml[:ss]] [[[dzn]] 


The tz must be a three-letter time-zone name, such as PST, followed by an option- 
ally signed number, + —hh, giving the difference in hours between UCT and local 
time. To specify the exact local time, the hours can be followed by minutes, :mm; 
seconds, :ss; and a three-letter daylight-saving-time zone, dzn, such as PDT. Sepa- 
rate hours, minutes, and seconds with colons (:). If daylight saving time is never in 
effect, as is the case in certain states and localities, set TZ without a value for dzn. 


If the TZ value is not currently set, the default is PST8PDT, which corresponds to 
the Pacific time zone. 


Return Value 


Compatibility 


See Also 


Example 
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Based on the TZ environment variable value, the following values are assigned to 
the variables _ daylight, _ timezone, and _ tzname when _ tzset is called: 


Variable Value 

_ daylight Nonzero value if a daylight-saving-time zone is specified in the 
TZ setting; otherwise, 0 

_timezone Difference in seconds between GMT and local time 

_tzname[0] String value of the three-letter time-zone name from the TZ 


environmental variable 


_tzname[1]| String value of the daylight-saving-time zone, or an empty string 
if the daylight-saving-time zone 1s omitted from the TZ 
environmental variable 


The default for _daylight is 1; for _ timezone, 28,800; for _tzname[0], PST; and 
for _tzname[1], PDT. This corresponds to “PST8PDT.” 


If the DST zone is omitted from the TZ environmental variable, the _ daylight 


variable will be 0 and the _ftime, gmtime, and localtime functions will return 0 
for their DST flags. 


None. 


Standards: UNIX 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 


Use _ tzset for compatibility with ANSI naming conventions of non-ANSI 
functions. Use tzset and link with OLDNAMES.LIB for UNIX compatibility. 


asctime, _ ftime, gmtime, localtime, time 


/* TZSET.C: This program first sets up the time zone by placing the variable 
* named TZ=EST5 in the environment table. It then uses _tzset to set the 
* global variables named _daylight, _timezone, and _tzname. 


dFinclude <time.h> 
dFinclude <stdlib.h> 
dFinclude <stdio.h> 
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void main( void ) 


{ 
TTC 2putenvG “TZ=ESTSEDT™ ) == <1_ 2) 
{ 
printf( "Unable to set TZ\n" ); 
exit 13% 
t 
else 
{ 
_tzset(); 
printf( "_daylight = %d\n", _daylight ); 
printf( “_timezone = %ld\n", _timezone ); 
printf( "_tzname[@] = %s\n", _tznameLl@] ); 
} 
exit( @ ); 
} 
Output _daylight = 1 
_timezone = 18000 


_tzname[Q@] = EST 


Description 


Remarks 


Return Value 


Compatibility 


See Also 


Example 
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_ultoa 
Converts an unsigned long integer to a string. 
#include <stdlib.h> Required only for function declarations 


char *_ultoa( unsigned long value, char *string, int radix ); 


value Number to be converted 
string String result 
radix Base of value 


The _ultoa function converts value to a null-terminated character string and stores 
the result (up to 33 bytes) in string. No overflow checking is performed. The radix 
argument specifies the base of value; it must be in the range 2—36. 


The _ultoa function returns a pointer to string. There is no error return. 


Standards: None 


16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 
_itoa, _Itoa 


/* ITOA.C: This program converts integers of various sizes to strings 
* in various radixes. 


d#Hinclude <stdlib.h> 
d#einclude <stdio.h> 
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void main( void ) 
£ 
char buffer[2@]; 
int i = 3445; 
long 1 = -344115L; 
unsigned long ul = 1234567890UL; 


_itoa( i, buffer, 10 ); 

printf( "String of integer %d (radix 10): %s\n", i, buffer ); 
_itoa( i, buffer, 16 ); 

printf( "String of integer 4d (radix 16): Ox%s\n", i, buffer ); 
_itoa( i, buffer, 2 ); 

printf( "String of integer %d (radix 2): %4s\n", i, buffer ); 


_ltoa( 1, buffer, 16 ); 
printf( "String of long int 41d (radix 16): Ox%s\n", 1, buffer ); 


_ultoa( ul, buffer, 16 ); 
printf( "String of unsigned long 4]lu (radix 16): @x%s\n", ul, buffer ); 


Output String of integer 3445 (radix 10): 3445 
String of integer 3445 (radix 16): @xd75 
String of integer 3445 (radix 2): 110101110101 
String of long int -344115 (radix 16): Oxfffabfcd 
String of unsigned long 1234567890 (radix 16): @x499602d2 


Description 


Remarks 


Return Value 
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—_ umask 


Sets the default file-permission mask. 


#include <sys\types.h> 
#include <sys\stat.h> 


#include <io.h> Required only for function declarations 
int _umask( int pmode ); 


pmode Default permission setting 


The _ umask function sets the file-permission mask of the current process to the 
mode specified by pmode. The file-permission mask is used to modify the permis- 
sion setting of new files created by _creat, _ open, or _sopen. If a bit in the mask 
is 1, the corresponding bit in the file’s requested permission value is set to O (disal- 
lowed). If a bit in the mask is 0, the corresponding bit is left unchanged. The per- 
mission setting for a new file is not set until the file is closed for the first time. 


The argument pmode is a constant expression containing one or both of the 
manifest constants _S_UREAD and _S_ITIWRITE, defined in SYS\STAT.H. 
When both constants are given, they are joined with the bitwise-OR operator (| ). 
The meaning of the pmode argument 1s as follows: 


Value Meaning 
_S_TREAD Reading not allowed (file is write-only) 
_S_ITWRITE Writing not allowed (file is read-only) 


For example, if the write bit is set in the mask, any new files will be read-only. 


Note that with DOS, all files are readable—tt is not possible to give write-only 
permission. Therefore, setting the read bit with _umask has no effect on the file’s 
modes. 


The _ umask function returns the previous value of pmode. There is no error 
return. 


Output 


826 _umask 
Compatibility Standards: UNIX 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 
Use _umask for compatibility with ANSI naming conventions of non-ANSI func- 
tions. Use umask and link with OLDNAMES.LIB for UNIX compatibility. 
See Also _chmod, _ creat, _ mkdir, _ open 
Example /* UMASK.C: This program uses _umask to set the file-permission mask so 


* that all future files will be created as read-only files. It also 
* displays the old mask. 
* / 


fHinclude <sys\types.h> 
#Hinclude <sys\stat.h> 
#Hinclude <io.h> 
#Hinclude <stdio.h> 


void main( void ) 


{ 

int oldmask; 

/* Create read-only files: */ 

oldmask = _umask( _S_IWRITE ); 

printf( "Oldmask = @x%.4x\n", oldmask ); 
} 


Oldmask = @xQ000 


Description 


Remarks 


Return Value 


Compatibility 


See Also 
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ungete 


Pushes a character back onto the stream. 
#include <stdio.h> 
int ungetc( int c, FILE *stream ); 


C Character to be pushed 


stream Pointer to FILE structure 


The ungetc function pushes the character c back onto stream and clears the end-of- 
file indicator. The stream must be open for reading. A subsequent read operation 
on the stream starts with c. An attempt to push EOF onto the stream using ungete 
is ignored. The ungetc function returns an error value if nothing has yet been read 
from stream or if c cannot be pushed back. 


Characters placed on the stream by ungetc may be erased if fflush, fseek, fsetpos, 
or rewind is called before the character is read from the stream. The file-position 
indicator will have the same value it had before the characters were pushed back. 
On a successful ungetce call against a text stream, the file-position indicator is un- 
specified until all the pushed-back characters are read or discarded. On each 
successful ungete call against a binary stream, the file-position indicator is 
stepped down; if its value was 0 before a call, the value is undefined after the call. 


Results are unpredictable if the ungetc function is called twice without a read 
operation between the two calls. After a call to the fscanf function, a call to 
ungetc may fail unless another read operation (such as the gete function) has been 
performed. This is because the fscanf function itself calls the ungete function. 


The ungetce function returns the character argument c. The return value EOF indi- 
cates a failure to push back the specified character. 


Standards: ANSI, UNIX 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 


getc, getchar, putc, putchar 
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Example /* UNGETC.C: This program first converts a character representation of an 
* unsigned integer to an integer. If the program encounters a character 
* that is not a digit, the program uses ungetc to replace it in the stream. 
* / 


#Hinclude <stdio.h> 
#Hinclude <ctype.h> 


void main( void ) 
1 

int ch; 

int result = Q; 


printf( "Enter an integer: " ); 


/* Read in and convert number: */ 
while( ((ch = getchar()) != EOF) && isdigit( ch ) ) 
result = result * 10 + ch - 'O'; /* Use digit. */ 
if( ch != EOF ) 
ungetc( ch, stdin ); /* Put non-digit back. */ 
printf( “Number = %d\nNext character in stream = ‘%c'\n", 
result, getchar() ); 


Output Enter an integer: 521a 
Number = 521 
Next character in stream = ‘a' 


_ungetch 829 


_ungetch 


Description Pushes back the last character read from the console. 
#include <conio.h> Required only for function declarations 
int _ungetch( int c ); 


C Character to be pushed 


Remarks The _ungetch function pushes the character c back to the console, causing c to be 
the next character read by _ getch or _ getche. The _ ungetch function fails if it 1s 
called more than once before the next read. The c argument may not be EOF. 


Return Value The _ungetch function returns the character c if it is successful. A return value of 
EOF indicates an error. 


Compatibility Standards: None 

16-Bit: DOS 

32-Bit: DOS32X 
See Also _escanf, _ getch, _ getche 


Example /* UNGETCH.C: In this program, a white-space delimited token is read 
* from the keyboard. When the program encounters a delimiter, 
* it uses _ungetch to replace the character in the keyboard buffer. 
* / 


d#Finclude <conio.h> 
#Hinclude <ctype.h> 
dFinclude <stdio.h> 


830 


Output 


_ungetch 


void main( void ) 
{ 
char buffer[10@]; 
int count = @; 
int ch; 


ch = _getche(); 

while( isspace( ch ) ) 
ch = _getche(); 

while( count < 99 ) 

{ 
if( isspace( ch ) ) 

break; 

bufferLcount++] = ch; 
ch = _getche(); 

} 

_ungetch( ch ); 

bufferLcount] = '\Q@'; 


/* Skip preceding white space. 


/* Gather token. */ 


/* End of token. */ 


/* Put back delimiter. */ 
/* Null terminate the token. 


printf( "\ntoken = %s\n", buffer ); 


White 
token = White 


* / 


Description 


Remarks 


Return Value 


Compatibility 


See Also 
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—_ unlink 
Deletes a file. 


#include <io.h> Required only for function declarations 
#include <stdio.h> Use either IO.H or STDIO.H 


int _unlink( const char *filename ); 


filename Name of file to remove 


The _ unlink function deletes the file specified by filename. 


If successful, _ unlink returns 0; otherwise, it returns —1 and sets errno to one of 
the following constants: 


Value Meaning 
EACCES Path name specifies a read-only file 
ENOENT File or path name not found, or path name specified a directory 


Standards: UNIX 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 


Use _ unlink for compatibility with ANSI naming conventions of non-ANSI func- 
tions. Use unlink and link with OLDNAMES.LIB for UNIX compatibility. 


_ close, remove 
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Example /* UNLINK.C: This program uses _unlink to delete UNLINK.OBJ. */ 
#Hinclude <stdio.h> 


void main( void ) 


{ 
if¢ _unlink( “_unlink.obj" ) == -1 ) 
perror( "Could not delete 'UNLINK.OBJ'" ); 
else 
printf( "Deleted "UNLINK.OBJ'\n" ); 
} 


Output Deleted 'UNLINK.OBJ' 
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_unregisterfonts 


Description Frees memory used by fonts. 
#include <graph.h> 


void __ far _ unregisterfonts( void ); 


Remarks The _unregisterfonts function frees memory previously allocated and used by the 
_registerfonts function. The _unregisterfonts function removes the header infor- 
mation for all fonts and unloads the currently selected font data from memory. 


Any attempt to use the _ setfont function or the _ outgtext function after calling 
_unregisterfonts results in an error. 


Return Value None. 
Compatibility Standards: None 
16-Bit: DOS 
32-Bit: None 
See Also _getfontinfo, _ getgtextextent, _outgtext, _registerfonts, _setfont 


Example See the example for _ outgtext. 


834 _utime 


Description 


Remarks 


Return Value 


Compatibility 


_utime 


Sets the file modification time. 


#include <sys\types.h> 


#include <sys\utime.h> 
int _utime( char “filename, struct _utimbuf “times ); 


filename Filename 


times Pointer to stored time values 


The _utime function sets the modification time for the file specified by filename. 
The process must have write access to the file; otherwise, the time cannot be 
changed. 


Although the _ utimbuf structure contains a field for access time, only the modifi- 
cation time is set with DOS. If times is a NULL pointer, the modification time 

is set to the current time. Otherwise, times must point to a structure of type 
_utimbuf, defined in SYS\UTIME.H. The modification time is set from the 
modtime field in this structure. 


The _utime function returns the value 0 if the file-modification time was changed. 
A return value of —1 indicates an error, and errno is set to one of the following 
values: 


Value Meaning 

EACCES Path name specifies directory or read-only file 

EINVAL Invalid argument; the times argument is invalid 

EMFILE Too many open files (the file must be opened to change its 
modification time) 

ENOENT File or path name not found 


Standards: UNIX 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X | 


Use _utime for compatibility with ANSI naming conventions of non-ANSI func- 
tions. Use utime and link with OLDNAMES.LIB for UNIX compatibility. 
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See Also asctime, ctime, _ fstat, _ ftime, gmtime, localtime, _ stat, time 


Example /* UTIME.C: This program uses _utime to set the file-modification time to 
* the current time. 
* / 


#Finclude <stdio.h> 
dHinclude <stdlib.h> 
dFinclude <sys\types.h> 
dFinclude <sys\utime.h> 


void main( void ) 
{ 
/* Show file time before and after. */ 
system( "dir _utime.c" ); 
if( _utime( "_utime.c", NULL ) == -1 ) 
perror( "_utime failed\n" ); 
else 
printf( "File time modified\n" ); 
system( "dir _utime.c" ); 


Output The volume label in drive C is ZEPPELIN. 
Directory of C:\LIBREF 


UTIME G 397 6-20-99 2:1lp 
1 File(s) 12974080 bytes free 
File time modified 


The volume label in drive C is ZEPPELIN. 
Directory of C:\LIBREF 


UTIME C 39 '/ 6-20-99 2:12p 
LP LLees) 12974080 bytes free 


836 va_arg, va_end, va_start 


Description 


Remarks 


va_arg, va_end, va_start 


Access variable-argument lists. 


#include <stdarg.h> Required for ANSI compatibility 
#include <varargs.h> Required for UNIX V compatibility 
#include <stdio.h> 


type va_arg( va_list arg_ptr, type ); 


void va_end( va_list arg_ptr ); 
void va_start( va_list arg_ptr ); UNIX version 


void va_start( va_list arg_ptr, prev_param ); ANSI 


arg_ptr Pointer to list of arguments 

prev_param Parameter preceding first optional argument 
(ANSI only) 

type Type of argument to be retrieved 


The va_arg, va_end, and va_start macros provide a portable way to access the 
arguments to a function when the function takes a variable number of arguments. 
Two versions of the macros are available: the macros defined in STDARG.H con- 
form to the ANSI C standard, and the macros defined in VARARGS.H are compat- 
ible with the UNIX System V definition. The macros are listed below: 


Macro Description 

va_alist Name of parameter to called function (UNIX version only) 
va_arg Macro to retrieve current argument 

va_dcel Declaration of va_alist (UNIX version only) 

va_end Macro to reset arg_ptr 

va_list The typedef for the pointer to list of arguments 

va_start Macro to set arg_ptr to beginning of list of optional arguments 


(UNIX version only) 
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Both versions of the macros assume that the function takes a fixed number of re- 
quired arguments, followed by a variable number of optional arguments. The re- 
quired arguments are declared as ordinary parameters to the function and can be 
accessed through the parameter names. The optional arguments are accessed 
through the macros in STDARG.H or VARARGS.H, which set a pointer to the 
first optional argument in the argument list, retrieve arguments from the list, and 
reset the pointer when argument processing is completed. 


The ANSI C standard macros, defined in STDARG.H, are used as follows: 


ie 


4. 


All required arguments to the function are declared as parameters in the usual 
way. The va_del macro is not used with the STDARG.H macros. 


. The va_start macro sets arg_ptr to the first optional argument in the list of ar- 


guments passed to the function. The argument arg_ptr must have va_list type. 
The argument prev_param is the name of the required parameter immediately 
preceding the first optional argument in the argument list. If prev_param is de- 
clared with the register storage class, the macro’s behavior is undefined. The 
va_start macro must be used before va_arg is used for the first time. 


. The va_arg macro does the following: 


" Retrieves a value of type from the location given by arg_ptr 


= Increments arg_ptr to point to the next argument in the list, using the size of 
type to determine where the next argument starts 


The va_arg macro can be used any number of times within the function to 
retrieve arguments from the list. 


After all arguments have been retrieved, va_end resets the pointer to NULL. 


The UNIX System V macros, defined in VARARGS.H, operate in a slightly differ- 
ent manner, as follows: 


l. 


Any required arguments to the function can be declared as parameters in the 
usual way. 


. The last (or only) parameter to the function represents the list of optional argu- 


ments. This parameter must be named va_alist (not to be confused with 
va_list, which is defined as the type of va_alist). 


. The va_dcel macro appears after the function definition and before the opening 


left brace of the function. This macro is defined as a complete declaration of the 
va_alist parameter, including the terminating semicolon; therefore, no semi- 
colon should follow va_dcl. 


. Within the function, the va_start macro sets arg_ptr to the beginning of the list 


of optional arguments passed to the function. The va_start macro must be used 
before va_arg is used for the first time. The argument arg_ptr must have 
va_list type. 
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5. The va_arg macro does the following: 
" Retrieves a value of type from the location given by arg_ptr 


= Increments arg_ptr to point to the next argument in the list, using the size of 
type to determine where the next argument starts 


The va_arg macro can be used any number of times within the function to 
retrieve the arguments from the list. 


6. After all arguments have been retrieved, va_end resets the pointer to NULL. 


Return Value The va_arg macro returns the current argument; va_start and va_end do not 
return values. 


Compatibility Standards: ANSI, UNIX 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 
See Also vfprintf 
Example /* VA.C: The program below illustrates passing a variable number of arguments 
* using the following macros: 
* va_start va_arg va_end 
** va_list | va_decl (UNIX only) 
* / 
#include <stdio.h> 
dtdefine ANSI /* Comment out for UNIX version * / 
#ifdef ANSI /* ANSI compatible version * / 
#Finclude <stdarg.h> 
int average( int first, ... ); 
ftelse /* UNIX compatible version * / 


#Hinclude <varargs.h> 
int average( va_list ); 
dtendif 


void main( void ) 

{ 
/* Call with 3 integers (-1 is used as terminator). */ 
printf( "Average is: %d\n", average( 2, 3, 4, -1 ) ); 


/* Call with 4 integers. */ 
printf( “Average is: %d\n", average( 5, 7, 9, 11, -1 ) ); 


/* Call with just -1 terminator. */ 
printf( "Average is: %d\n", average( -1 ) ); 


Output 


va_arg, va_end, va_start 


/* Returns the average of a variable list of integers. */ 


ifdef ANSI /* ANSI compatible version + / 
int average( int first, ... ) 
{ 


int count = @, sum = 9, i = first; 
va_list marker; 


va_start( marker, first ); /* Initialize variable arguments. */ 
while( i != -1 ) 
{ 
Sum += 1; 
count++; 
1 = va_arg( marker, int); 
} 
va_end( marker ); /* Reset variable arguments. * / 
return( sum ? (sum / count) : @ ); 
} 
fFelse /* UNIX compatible version must use old-style definition. */ 
int average( va_alist ) 
va_dcl 
{ 
int 1, count, sum; 
va_list marker; 
va_Start( marker ); /* Initialize variable arguments. */ 
for( sum = count = @; (i = va_arg( marker, int)) != -1; count++ ) 
Sum += 1; 
va_end( marker ); /* Reset variable arguments. * / 
return( sum ? (sum / count) : @ ); 
} 
fendi f 


Average is: 3 
Average is: 8 
Average is: @ 
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840 ~=—- Vprintf, vprintf, vsprintf, _ vsnprintf 


Description 


Remarks 


viprintf, vprintf, vsprintf, _ vsnprintt 


Write formatted output using a pointer to a list of arguments. 


#include <stdio.h> 
#include <varargs.h> Required for UNIX System V compatibility 
#include <stdarg.h> Required for ANSI compatibility 


int vfprintf( FILE “stream, const char *format, va_list argptr ); 
int vprintf( const char *format, va_list argptr ); 
int vsprintf( char “buffer, const char *format, va_list argptr ); 


int _ vsnprintf( char “buffer, size_t count, const char *format, va_list argptr ); 


stream Pointer to FILE structure 
format Format control 

argptr Pointer to list of arguments 
buffer Storage location for output 
count Maximum number of bytes 


The vfprintf, vprintf, and vsprintf functions format data and output data to the 
file specified by stream, to standard output, and to the memory pointed to by 
buffer, respectively. The _ vsnprintf function differs from vsprintf in that it writes 
not more than count bytes to buffer. These functions are similar to their counter- 
parts fprintf, printf, and sprintf, but each accepts a pointer to a list of arguments 
instead of an argument list. 


The format argument has the same form and function as the format argument for 
the printf function; see printf for a description of format. 


The argptr parameter has type va_list, which is defined in the include files 
VARARGS.H and STDARG.H. The argptr parameter points to a list of arguments 
that are converted and output according to the corresponding format specifications 
in the format. 


Return Value 


Compatibility 


See Also 
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The return value for vprintf, vsprintf, and _ vsnprintf is the number of characters 
written, not counting the terminating null character. For _ vsnprinttf, if the number 
of bytes to write exceeds buffer, then count bytes are written and —1 1s returned. If 
successful, the vfprintf return value is the number of characters written. If an out- 
put error occurs, it is a negative value. 


vfprintf, vsprintf 
Standards: ANSI, UNIX 


16-Bit: DOS, QWIN, WIN 
32-Bit: DOS32X 

vprintf 

Standards: ANSI, UNIX 
16-Bit: DOS, QWIN 
32-Bit: DOS32X 
_vsnprintf 


Standards: None 
16-Bit: DOS, QWIN 
32-Bit: DOS32X 


fprintf, printf, sprintf, va_ arg, va_end, va_ start 
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Example 


/* 


** 


*« / 


VPRINTF.C shows how to use vprintf functions to write new versions 
of printf. The vsprintf function is used in the example. 


#Hinclude <stdio.h> 
#Hinclude <graph.h> 
#Hinclude <string.h> 
#Hinclude <stdarg.h> 
#Hinclude <malloc.h> 


int wprintf( short row, short col, short clr, long bclr, char *fmt, ... ); 


void main( void ) 


{ 
Short fgd = Q; 
long bgd = @L; 
_clearscreen( _GCLEARSCREEN ); 
_outtext( "Color text example:\n\n" ); 
/* Loop through 8 background colors. */ 
for( bgd = OL; bgd < 8; bgd++ ) 
{ 
wprintf( (int)bgd + 3, 1, 7, bgd, “Back: %d Fore:", bgd ); 
/* Loop through 16 foreground colors. */ 
for( fgd = 0; fgd < 16; fgdt+ ) 
wprintf( -1, -1, fgd, -1L, " 42d ", fgd ); 
i; 
ve 
/* Full-screen window version of printf that takes row, column, textcolor, 
* and background color as its first arguments, followed by normal printf 
* format strings (except that \t is not handled). You can specify -1 for 
* any of the first arguments to use the current value. The function returns 
* the number of characters printed, or a negative number for errors. 
* / 
int wprintf( short row, short col, short clr, long bclr, char *fmt, ... ) 
{ 


struct _rccoord tmppos; 
short ret, size; 
va_list marker; 

char *buffer; 


/* It's probably safe to use a buffer length of 512 bytes or five times 
* the length of the format string. 
* / 
size = strlen( fmt ); 
size = (size > 512) ? 512 : size * 5; 
if( (buffer = (char *)malloc( size )) == NULL ) 
return -1; 
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/* Set text position. */ 
tmppos = _gettextposition(); 
if( row < 1 ) 

row = tmppos.row; 
Itt Col <4) 

col = tmppos.col; 
_settextposition( row, col ); 


/* Set foreground and background colors. */ 
1tCclYr >= 0) 

_settextcolor( clr ); 
if( belr >= @ ) 

_setbkcolor( beclr ); 


/* Write text to a string and output the string. 


va_start( marker, fmt ); 

ret = vsprintf( buffer, fmt, marker ); 
va_end( marker ); 

_outtext( buffer ); 

free( buffer ); 

return ret; 
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844 _Vviree 


Description 


Remarks 


Return Value 


Compatibility 


See Also 


Example 


_vtree 


Deallocates a virtual memory block. 
#include <vmemory.h> 
void __ far _ vfree( _ vmhnd_t handle ); 


handle Handle to previously allocated virtual memory 
block 


The _ vfree function deallocates a virtual memory block. The argument handle 
points to a virtual memory block previously allocated through a call to __ vmalloc 
or _vrealloc. The number of bytes freed is the number of bytes specified when the 
block was allocated (or reallocated, in the case of _ vrealloc). The block must be 
unlocked before it is freed; use _ vlockent to ensure that the block is unlocked. 
After the call, the freed block is available for reuse by the virtual heap. 


None. 


Standards: None 
16-Bit: DOS 
32-Bit: None 


_vlock, _ vlockent, _ vmalloc, _ vrealloc, — vunlock 


See the example for _ vmalloc. 


Description 


Remarks 


_vheapinit 845 


_vheapinit 


Initializes the virtual memory manager. 
#include <vmemory.h> 


int __ far _vheapinit( unsigned int dosmin, unsigned int dosmax, 
unsigned int swaparea ); 


dosmin Minimum amount of DOS memory that must be 
available for the virtual memory manager to install 
itself, in paragraphs 


dosmax Maximum amount of DOS memory that the virtual 
memory manager can use, in paragraphs 


swaparea Type of auxiliary memory to use 


The _ vheapinit routine initializes the virtual memory manager in preparation 
for future allocations. It must be called before any virtual memory blocks are 
requested. 


The _ vheapinit function may round up the minimum value specified. After round- 
ing, if the minimum amount of DOS memory is not available, _ vheapinit does 
not initialize the virtual memory manager and returns 0. The virtual memory 
manager requires several kilobytes to function effectively. 


If_ VM_ALLDOS is specified for the dosmax argument, the virtual memory 
manager uses all available DOS memory. 


The swaparea argument specifies which types of auxiliary memory the virtual 
memory manager can use to hold blocks of memory that are swapped out. The 
argument can be one or more of the following manifest constants, combined with 
the bitwise-OR operator (| ): 


Value Meaning 

_VM_EMS Use expanded memory 
_VM_XMS Use extended memory 
_VM_DISK Use disk space 


—~VM_ALLSWAP (_VM_EMS!_VM_XMS|_VM_DISK ) 


If not all of the specified forms of storage are available, the virtual memory 
manager uses what is available. 
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Return Value 


Compatibility 


See Also 


Example 


After the program is done using virtual memory, it must call _ vheapterm to termi- 
nate the virtual memory manager. A program can contain multiple pairs of 
_ vheapinit /_ vheapterm calls. 


Warning! If the program terminates without a call to_vheapterm, various system 
memory resources may not be available to subsequent programs. 


To specify that no minimum amount of memory is required for installation of the 
virtual memory manager and to use all available DOS memory in the virtual heap 
and all auxiliary storage, use the following command: | 


if( _vheapinit( @, _VM_ALLDOS, _VM_ALLSWAP) == @ ) 
/* Error */ 


The _ vheapinit function returns a nonzero value if the virtual memory manager 
was successfully initialized. Otherwise, it returns 0. 


Standards: None 


16-Bit: DOS 
32-Bit: None 
_vheapterm 


See the example for _ vmalloc. 
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_vheapterm 


Description Terminates the virtual memory manager. 
#include <vmemory.h> 


void __ far _ vheapterm( void ); 


Remarks The _ vheapterm function terminates the virtual memory manager and releases all 
resources that it used. 


Warning! If the program terminates without a call to_vheapterm, various system 
memory resources may not be available to subsequent programs. 


If the virtual memory manager has not been initialized or has already been termi- 
nated when _ vheapterm is called, the function returns immediately. 


Return Value None. 
Compatibility Standards: None 
16-Bit: DOS 
32-Bit: None 
See Also _vheapinit 


Example See the example for _ vmalloc. 
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Description 


Remarks 


Return Value 


Compatibility 


See Also 


_vload 


Loads a virtual memory block into DOS memory. 
#include <vmemory.h> 


void __ far *__ far _ vload( __vmhnd_t handle, int dirty ); 


handle Handle to previously allocated virtual memory 
block 
dirty Flag indicating whether the block should be writ- 


ten out or discarded when swapping occurs 


The — vload function loads a virtual memory block into DOS memory and returns 
a far pointer to it. The argument handle points to a virtual memory block pre- 
viously allocated through a call to _ vmalloc or _ vrealloc. 


The block of memory is not locked and may be swapped out if the virtual memory 
manager needs the memory. Consequently, the pointer returned by _ vload is valid 
only until the next call to the virtual memory manager. 


The dirty flag indicates whether the block of memory should be written out or 
discarded when swapping occurs. It can have one of the following values: 


Value Meaning 

_VM_ CLEAN Discard contents of block when swapping occurs 

_VM_ DIRTY Write contents of block to auxiliary memory when swapping 
occurs 


The _ vload function returns a far pointer to DOS memory if the virtual memory 
block is successfully loaded. If insufficient DOS memory is available, _ vload 
returns NULL. 


Standards: None 
16-Bit: DOS 
32-Bit: None 


_vlock, _ vmalloc, _ vunlock 


Example 
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/* VLOAD.C: This program loads a block of virtual memory with _vload, 

* writes to it, and loads in a new block. It then reloads the first block 
* and verifies that its contents haven't changed. 

a / 


d4Finclude <stdio.h> 
#Ainclude <stdlib.h> 
#Hinclude <vmemory.h> 


void main( void ) 
{ 
int i, flag; 
_vmhnd_t handlel, 
handle2; 
int __far *bufferl; 
int __far *buffer2; 


if ( !_vheapinit( @, _VM_ALLDOS, _VM_XMS | _VM_EMS ) ) 


{ 
printf( “Could not initialize virtual memory manager. \n" ); 
Oxttt 1. }% 
} 
if ( ( (handlel = _vmalloc( 10@ * sizeof(int) )) == _VM_NULL ) || 
( (handle2 = _vmalloc( 100 * sizeof(int) )) == _VM_NULL ) ) 
{ 
_vheapterm(); 
exite <1. )% 
} 


printf( "Two blocks of virtual memory allocated.\n" ); 


if ( (bufferl = (int __far *)_vload( handlel, _VM_DIRTY )) == NULL ) 
{ 

_vheapterm(); 

exit( -1 ); 
} 


printf( “bufferl loaded: valid until next call to VM manager.\n" ); 
for ( i = 0; i 100; i++ ) /* write to bufferl */ 
bufferl[Li] d= i; 


if ( (buffer2 = (int __far *)_vload( handle2, _VM_ DIRTY )) == NULL ) 
{ 

_vheapterm(); 

Oxi. 215s 
} 


printf( “buffer2 loaded. buffer 1 no longer valid.\n" ); 
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Output 


_vioad 


if ( (bufferl = (int __far *)_vload( handlel, _VM_CLEAN )) == NULL ) 
{ 

_vheapterm(); 

exTt© al Js 
} 


printf( “bufferl reloaded.\n" ); 


flag = @; 
for ( i = 0; i 100; i++ ) 
if ( bufferl{fi] != 7 ) 
flag = 1; 


if ( !flag ) 
printf( "Contents of bufferl verified.\n" ); 


_vfree( handlel ); 
_vfree( handle2 ); 
_vheapterm(); 
exit( @ ); 


Two blocks of virtual memory allocated. 

bufferl loaded: valid until next call to VM manager. 
buffer2 loaded. buffer 1 no longer valid. 

bufferl reloaded. 

Contents of bufferl verified. 


Description 


Remarks 


Return Value 


Compatibility 


See Also 


_vilock 851 


_ vlock 


Loads a virtual memory block into DOS memory and locks it. 
#include <vmemory.h> 
void __ far *__ far _ vlock( _ vmhnd_t handle ); 


handle Handle to previously allocated virtual memory 
block 


The _ vlock function loads a virtual memory block into DOS memory, locks it, 
and returns a far pointer to it. The argument handle points to a virtual memory 
block previously allocated through a call to_vmalloc or _ vrealloc. 


A locked virtual memory block will not be swapped out until it is unlocked. A vir- 
tual memory block can be locked up to 255 times. The pointer returned by _ vlock 
remains valid until an equal number of unlock operations is performed. 


Since DOS memory may be scarce, try to keep the number of blocks locked at one 
time to a minimum and use _ vunlock to unlock them as soon as possible. 


The _ vlock function returns a far pointer to DOS memory if the virtual memory 
block is successfully loaded and locked. If insufficient DOS memory is available, 
_Vload returns NULL. 


Standards: None 
16-Bit: DOS 
32-Bit: None 


_vlockent, _ vmalloc, _ vunlock 
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Example 


_vlock 


/* VLOCK.C: This program locks a block of virtual memory using _vlock, 
* writes to it, loads in a new block with _vload, and then verifies 

* that the contents of the locked block are still accessible. It then 
* unlocks the block with _vunlock. 

re / 


dHinclude <stdio.h> 
dHinclude <stdlib.h> 
fHinclude <vmemory.h> 


void main( void ) 
{ 
int i, flag; 
_vmhnd_t handlel, 
handle2; 
int __far *bufferl; 
int __far *buffer2; 


if ( !_vheapinit( @, _VM_ALLDOS, _VM_XMS | _VM_EMS ) ) 


{ 
printf( "Could not initialize virtual memory manager. \n" ); 
exit( -1 ); 
} 
if ( ( (handlel = _vmalloc( 100 * sizeof(int) )) == _VM_NULL ) || 
( (handle2 = _vmalloc( 100 * sizeof(int) )) == _VM_NULL ) ) 
{ 
_vheapterm(); 
exit( -1 ); 
} 


printf( "Two blocks of virtual memory allocated.\n" ); 


if ( (bufferl = (int __far *)_vlock( handlel )) == NULL ) 
{ 

_vheapterm(); 

exit( -1 ); 
} 


printf( “bufferl locked: valid until unlocked.\n" ); 
for ( i = @; i 100; i++ ) // write to bufferl 
bufferlLi] = 1; 


if ( (buffer2 = (int __far *)_vload( handle2, _VM_DIRTY )) == NULL ) 
. 

_vheapterm(); 

exit( -1 ); 


Output 


_vilock 


printf( “buffer2 loaded. buffer 1 still valid.\n" ); 


flag = Q; 
for ( i = 0; i 100; i++ ) 
if ( bufferl[i] != 7 ) 
flag = 1; 


if ( !flag ) 
printf( "Contents of bufferl verified.\n" ); 


_vunlock( handlel, _VM_DIRTY ); 
_vfree( handlel ); 

_vfree( handle2 ); 
_vheapterm(); 

exit( @ ); 


Two blocks of virtual memory allocated. 
bufferl locked: valid until unlocked. 
buffer2 loaded. buffer 1 still valid. 
Contents of bufferl verified. 
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854 _vlockent 


Description 


Remarks 


Return Value 


Compatibility 


See Also 


Example 


_ vlockent 


Returns the number of times a virtual memory block was locked. 
#include <vmemory.h> 
unsigned int __ far _ vlockcent(__vmhnd_t handle ); 


handle Handle to previously allocated virtual memory 
block 


The — vlockent function returns the number of times a virtual memory block has 
been locked. The argument handle points to a virtual memory block previously 
allocated through a call to _vmalloc or _ vrealloc. Use the _ vlockent function to 
ensure that a block is unlocked before it is freed (using _ vfree). 


The _ vlockent function returns the number of locks held on the specified virtual 


memory block. 

Standards: None 
16-Bit: DOS 
32-Bit: None 


_vlock, _ vmalloc, — vunlock 


/* VCNT.C: This program locks a block of virtual memory five times with 
* _vlock, and then unlocks it five times with _vunlock, calling 

* vlockcnt after each operation to report the number of locks held. 

* / 


#Hinclude <stdio.h> 
#Hinclude <stdlib.h> 
#Hinclude <vmemory.h> 
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void main( void ) 

{ 
int i, count; 
_vmhnd_t handle; 
int __far *buffer; 


if ( !_vheapinit( @, _VM_ALLDOS, _VM_XMS | _VM_EMS ) ) 


{ 
printf( "Could not initialize virtual memory manager. \n" ); 
exit( -1 ); 
} 
if ( (handle = _vmalloc( 100 * sizeof(int) )) == _VM_NULL ) 
{ 
_vheapterm(); 
OxTEt=E 3) 
} 


printf( "Block of virtual memory allocated.\n" ); 


printf( "Locking...\n" ); 
for ( i = 0; i 5; itt ) 


{ 
if ( (buffer = (int __far *)_vlock( handle )) == NULL ) 
{ 
_vheapterm(); 
exitt -L ); 
} 
count = _vlockcnt( handle ); 
printf( "%d locks held.\n", count ); 
} 


printf("Unlocking...\n" ); 
for ( i = 03; i 5; i++ ) 


{ 

_vunltock( handle, _VM_CLEAN ); 

count = _vlockcnt( handle ); 

printf( "%d locks held.\n", count ); 
} 


_vfree( handle ); 
_vheapterm(); 
exit( @ ); 
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Output Block of virtual memory allocated. 
Locking... 
1 locks held. 
2 locks held. 
3 locks held. 
4 locks held. 
5 locks held. 
Unlocking... 
4 locks held. 
3 locks held. 
locks held. 
locks held. 
locks held. 


QO FP 


Description 


Remarks 


Return Value 


Compatibility 


See Also 
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_vmalloc 


Allocates a virtual memory block. 
#include <vmemory.h> 
_vmhnd_t __ far —vmalloc( unsigned long size ); 


size Bytes to allocate 


The _ vmalloc function allocates a virtual memory block of at least size bytes. The 
actual size of the allocated block may be larger than size bytes to allow the virtual 
memory manager to operate more efficiently; use _ vmsize to find the actual size 
of the block. 


The value returned by _ vmalloc is a handle that uniquely identifies the virtual 
memory block. This value is not an address and cannot be used to access memory 
directly. The value must be passed to either the _ vload or _ vlock function to ob- 
tain a valid address. 


The _ vmalloc function returns a handle to the allocated virtual memory block, or 
_VM_NULL if insufficient memory is available or if the requested block size is 
too large to load into DOS memory. 


Standards: None 
16-Bit: DOS 
32-Bit: None 


_vfree, _ vmsize, _ vrealloc 
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Example /* VMALLOC.C: This program initializes the virtual memory manager with 
_vheapinit and allocates a block of virtual memory with _vmalloc. 
It then frees the memory with _vfree, and terminates the virtual 

* memory manager with _vheapterm. 

* / 


x * 


#Finclude <stdio.h> 
#FAinclude <stdlib.h> 
#include <vmemory.h> 


void main( void ) 


{ 
_vmhnd_t handle; 
if ( !_vheapinit( @, _VM_ALLDOS, _VM_XMS | _VM_EMS ) ) 
{ 
printf( "Could not initialize virtual memory manager.\n" ); 
exit( -l ); 
} 
printf( "Requesting 100 bytes of virtual memory.\n" ); 
if ( (handle = _vmalloc( 10@ )) == _VM_NULL ) 
{ 
_vheapterm(); 
exit( =1:)% 
} 
printf( "Received block of virtual memory.\n" ); 
_vfree( handle ); 
_vheapterm(); 
exit( @ ); 
J 
Output Requesting 100 bytes of virtual memory. 


Received block of virtual memory. 


Description 


Remarks 


Return Value 


Compatibility 


See Also 


Example 
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_vmsize 


Returns the size of a virtual memory block. 
#include <vmemory.h> 
unsigned long __ far _ vmsize( _vmhnd_t handle ): 


handle Handle to previously allocated virtual memory 
block 


The _ vmsize function returns the size, in bytes, of a virtual memory block. The 
argument handle points to a virtual memory block previously allocated through a 
call to __vmalloc or _ vrealloc. The size returned may be larger than the size re- 
quested in the call to _ vmalloc or _ vrealloc. 


The _ vmsize function returns the size (in bytes) of the specified virtual memory 
block as an unsigned long. 


Standards: None 


16-Bit: DOS 
32-Bit: None 
_vmatlloc 


See the example for _ vrealloc. 
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Description 


Remarks 


Return Value 


Compatibility 


See Also 


_ vrealloc 


Reallocates a virtual memory block. 
#include <vmemory.h> 


_vmhnd_t __ far _ vrealloc( _ vmhnd_t handle, unsigned long size ); 


handle Handle to previously allocated virtual memory 
block 
size New size in bytes 


The _ vrealloc function changes the size of a virtual memory block. If handle is 
_VM_NULL, _vrealloc behaves in the same way as _ vmalloc and allocates a 
new block of size bytes. If handle is not _VWM_NULL, it must point to a virtual 
memory block previously allocated through a call to__ vmalloc or _ vrealloc. 


The size argument gives the new size of the block, in bytes. The size of the block 
may be larger than size bytes to allow the virtual memory manager to operate 
more efficiently; use _ vmsize to find the actual size of the block. The contents of 
the block are unchanged up to the shorter of the new and old sizes, although the 
new block may be in a different location. 


The _ vrealloc functions returns a handle to the reallocated (and possibly moved) 
virtual memory block. 


The return value is__WM__NULL if the size specified is zero and the handle argu- 
ment is not_VM_NULL. In this case, the original block is freed. 


The return value is also_ VM_ NULL if there is not enough available memory to 
expand the block to the requested size, if the requested block size is too large to 
load into DOS memory, or if the given handle is still locked. In these cases, the 
original block is still valid. | 


Standards: None 
16-Bit: DOS 
32-Bit: None 


_vfree, _ vmalloc, _ vmsize 


Example 


Output 


/* 


* / 


_Vvrealloc 


VRSIZE.C: This program allocates a block of virtual memory with 
_vmalloc and uses _vmsize to display the size of that block. Next, 
it uses _vrealloc to expand the amount of virtual memory and calls 
_vmsize again to display the new amount of memory allocated. 


#Hinclude <stdio.h> 
#Finclude <stdlib.h> 
#Hinclude <vmemory.h> 


void main( void ) 


{ 


_vmhnd_t handle; 
unsigned long block_size; 


if ( !_vheapinit( @, _VM_ALLDOS, _VM_XMS | _VM_EMS ) ) 
{ 
printf( "Could not initialize virtual memory manager.\n" ); 
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} 
printf( "Requesting 100 bytes of virtual memory.\n" ); 
if ( (handle = _vmalloc( 100 )) == _VM_NULL ) 
{ 
_vheapterm(); 
exit( -l ); 
} 
block_size = _vmsize( handle ); 


printf( “Received %d bytes of virtual memory.\n", block_size ); 


printf( "Resizing block to 20@ bytes.\n" ); 
if ( (handle = _vrealloc( handle, 20@ )) == _VM_NULL ) 
{ 
_vheapterm(); 
OX1tC- =i % 
} 


block_size = _vmsize( handle ); 
printf( "Block resized to %d bytes.\n", block_size ); 


_vfree( handle ); 
_vheapterm(); 
exit( @ ); 


Requesting 100 bytes of virtual memory. 
Received 10@ bytes of virtual memory. 
Resizing block to 200 bytes. 

Block resized to 200 bytes. 
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862 _ vunlock 


Description 


Remarks 


Return Value 


Compatibility 


See Also 


Example 


—_ vunlock 


Unlocks a virtual memory block. 
#include <vmemory.h> 


void __ far _ vunlock( _ vmhnd_t handle, int dirty ); 


handle Handle to previously allocated virtual memory 
block 
dirty Flag indicating whether block should be written 


out or discarded when swapping occurs 


The — vunlock function unlocks a virtual memory block. The argument handle 
points to a virtual memory block previously allocated through a call to _ vmalloc 
or _ vrealloc and locked through a call to _ vlock. 


If multiple locks are held on the virtual memory block, the block’s lock count is 
decremented by one. If the block’s lock count goes to zero, the block can be 
swapped out by the virtual memory manager. The pointer returned by _ vlock 
when the block was first locked then becomes invalid. 


The dirty flag indicates whether the block should be written out or discarded when 
Swapping occurs. It can have one of the following values: 


Value Meaning 

_VM_ CLEAN Discard contents of block when swapping occurs 

_ VM_ DIRTY Write contents of block to auxiliary memory when swapping 
occurs 

None. 


Standards: None 
16-Bit: DOS 
32-Bit: None 


_vlock, _ vlockcnt, _ vmalloc 


See the example for _ vlock. 
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_wabout 


Description Sets the string that appears in the About dialog box of a QuickWin program. 
#include <io.h> 
int _ wabout( char “string ); 


string Pointer to a null-terminated string 


Remarks The _ wabout function sets the string that appears in the About dialog box of a 
Quick Win program. This routine is used only in Quick Win programs; it 1s not part 
of the Windows API. For full details about QuickWin, see Chapter 8 of Program- 
ming Techniques (in the Microsoft C/C++ version 7.0 documentation set). 


When the user chooses the About command from the Help menu, a dialog box ap- 
pears containing the string set with _ wabout. If a Quick Win program does not in- 
clude a call to__ wabout, information about Quick Win itself is displayed by 
default. 


The maximum string length is 256 bytes. 


Return Value If successful, _ wabout returns 0. A nonzero return value indicates an error. 
Compatibility Standards: None 

16-Bit: QWIN 

32-Bit: None 
See Also _fwopen, _ wclose, _ wgetexit, _ wgetfocus, _ wgetscreenbuf, _ wgetsize, 


_ wmenuclick, _ wopen, _ wsetexit, _ wsetfocus, _ wsetscreenbuf, _ wsetsize, 
_wyield 
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Example /* WABOUT.C - Demonstrate setting the About dialog box 
* String with _wabout 
* / 


dEinclude <stdio.h> 
dHinclude <io.h> 


char string[512]; 


void main( void ) 
af 


int nRes; 


fOr Cs. 2) 

ie 
printf( "\nEnter the About string: " ); 
scanf("%s", string); 
printf( "\nAbout string = %s\n", string ); 


printf( "Setting about string..." ); 
nRes = _wabout( string ); 
printf( "\n_wabout result = %i\n", nRes ); 


printf( "\nTry 'About' in the Help menu\n" );_ 


Description 


Remarks 


Return Value 
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_welose 


Closes a Quick Win window’ s file handle. 
#include <io.h> 
int _ wclose( int wfh, int persist ); 


wth File handle to a Quick Win window 


persist Flag indicating whether the window stays on the 
screen after closing 


The _ welose function closes a QuickWin window. The window must have been 
previously opened with the Quick Win function _wopen. This routine is used only 
in Quick Win programs; it is not part of the Windows API. For full details about 
QuickWin, see Chapter 8 of Programming Techniques (in the Microsoft C/C++ 
version 7.0 documentation set). 


To close a window opened with _ wopen, pass its file handle to _ welose. To close 
a window opened with _fwopen, call the STDIO.H function felose. 


The persist flag can have one of the following values: 


Value Meaning 
_WINNOPERSIST Erase the closed window 
—_WINPERSIST Leave the window on the screen 


If the window remains on the screen, another _ welose call to the same file handle 
with _ WINNOPERSIST removes it. While the window remains visible, the user 
can copy and paste text in it, choose QuickWin menus, and operate the window’ s 
scroll bars. 


Regardless of which persist option is used, the window’s file handle is closed to 
all further I/O. If a window is opened with the same title as a window closed with 
persistence, it will be a different window. Windows closed with persistence count 
against the total number of open windows (20 by default). 


If successful, _ welose returns 0. A return value of —1 indicates an error; errno is 
set to EBADF, indicating an invalid file-handle argument. 
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Compatibility 


See Also 


Example 


Standards: None 

16-Bit: QWIN 

32-Bit: None 

_fwopen, _ wabout, _ wgetexit, _ wgetfocus, _ wgetscreenbuf, _ wgetsize, 


_ wmenuclick, _ wopen, _ wsetexit, _ wsetfocus, _ wsetscreenbuf, _ wsetsize, 
_wyield 


/* WCLOSE.C - Demonstrate closing QuickWin windows */ 


#Ainclude <fcntl.h> 
d#Finclude <stdio.h> 
d#Finclude <io.h> 


#define PERSISTFLAG _WINNOPERSIST 
##define OPENFLAGS _O_RDWR 


void main( void ) 


{ 


int wfh; /* File handle for window */ 
int nRes; /* Window write results */ 
int wc; /* Window closure results */ 


struct _wopeninfo wininfo; /* Open information */ 


/* Set up window open information */ 
wininfo._version = _WINVER; 
wininfo._ title = "Window Closing"; 
wininfo._bufsize = _WINBUFDEF; 


/* Open a window with _wopen */ 
wfh = _wopen( &wininfo, NULL, OPENFLAGS ); 
LEC WHh-S= A152) 
{ 
printf( "***ERROR: On _wopen\n" ); 
expe G =k Os 
} 


/* Write in the window */ 
nRes = write( wfh, "Windows Everywhere! \n", 20 ); 


/* Close the window with _wclose */ 
wc = _wclose( wfh, PERSISTFLAG ); 


exit( Q@ ); 


Description 


Remarks 


Return Value 
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westombs, _fwestombs 


Convert a sequence of wide characters to a corresponding sequence of multibyte 
characters. 


#include <stdlib.h> 


size_t westombs( char *mbstr, const wchar_t *wcstr, size_t count ); 


size_t __far _fwcestombs( char __ far *mbstr, const wchar_t __ far *westr, 
size_t count ); 


mbstr The address of a sequence of multibyte characters 
westr The address of a sequence of wide characters 
count The number of bytes to convert 


The westombs function converts count or fewer wide characters pointed to by 
westr to the corresponding multibyte characters and stores the results in the mbstr 
array. 


If westombs encounters the wide-character null character (L’\0’) either before or 
when count occurs, it converts it to the multibyte null character (a 16-bit 0) and 
stops. Thus, the multibyte character string at mbstr is null-terminated only if 
westombs encounters a wide-character null character during conversion. If the 
sequences pointed to by westr and mbstr overlap, the behavior of westombs is 
undefined. 


The _fwestombs function is a model-independent (large-model) form of the 
westombs function. 


If either westombs or _fwestombs successfully converts the multibyte string, it re- 
turns the number of converted multibyte characters, excluding the wide-character 
null character. If either function encounters a wide character that cannot be con- 
verted to a multibyte character, it returns —1 cast to type size_t. 
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Compatibility westombs 
Standards: ANSI 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 
_fwestombs 


Standards: None 


16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: None 
See Also mblen, mbstowcs, mbtowc, wctomb, MB_CUR_MAX, MB_LEN_MAX 


Example /* WCSTOMBS.CPP illustrates the behavior of the wcstombs function */ 


#Hinclude <stdio.h> 
#Hinclude <stdlib.h> 


void main( void ) 


{ 
int 1 
char *xpmbbuf = (char *)malloc( MB_CUR_MAX ); 
wchar_t *pwcEOL = L'\Q'; 
wchar_t *pwchello = L"Hello, world."; 
printf( "Convert entire wide-character string:\n" ); 
1 = wcstombs( pmbbuf, pwchello, MB_CUR_MAX ); 
printf( "\tCharacters converted: Zu\n", i ); 
printf( "\tMultibyte character: %s\n\n", pmbbuf ); 
printf( "Attempt to convert null character:\n" ); 
i = wcstombs( pmbbuf, pwcEOL, MB_CUR_MAX ); 
printf( "\tCharacters converted: %4u\n", i ); 
printf( "\tMultibyte character: %s\n\n", pmbbuf ); 

} 

Output Convert entire wide-character string: 


Characters converted: 1 
Multibyte character: H 


Attempt to convert null character: 
Characters converted: Q 
Multibyte character: 


Description 


Remarks 


Return Value 


Compatibility 


See Also 
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wctomb, _fwctomb 


Convert a wide character to the corresponding multibyte character. 
#include <stdlib.h> 


int wctomb( char *mbchar, wchar_t wchar ); 


int __ far _fwctomb( char __ far *mbchar, wchar_t wchar ); 


mbchar The address of a multibyte character 


wchar A wide character 


The wetomb function converts its wchar argument to the corresponding multibyte 
character and stores the result at mbchar. 


The _fwetomb function is a model-independent (large-model) form of the 
wctomb function. It can be called from any point in any program. 


If either wctomb or _fwetomb converts the wide character to a multibyte 
character, it returns the number of bytes—which is never greater than 
MB_CUR_MAX—in the wide character. If wchar is the wide-character null 
character (L’\0’), wetomb returns 0. If the conversion is not possible in the 
current locale, wetomb returns —1. 


wctomb 

Standards: ANSI 

16-Bit: DOS, QWIN, WIN, WIN DLL | 
32-Bit: DOS32X 

_fwetomb 


Standards: None 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: None 


mblen, mbstowcs, mbtowc, wcstombs, MB_CUR_MAX, MB_LEN_MAX 
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Example /* WCTOMB.CPP illustrates the behavior of the wctomb function */ 


dEinclude <stdio.h> 
dFinclude <stdlib.h> 


void main( void ) 


{ 
int 7: 
wchar_t we = L'a'; 
char *pmbnull = NULL; 
char *pmb = (char *)malloc( sizeof( char ) ); 
printf( "Convert a wide character:\n" ); 
7 = wctomb( pmb, wc ); 
printf( "\tCharacters converted: “4u\n", i ); 
printf( "\tMultibyte character: %.1s\n\n", pmb ); 
printf( "Attempt to convert when target is NULL:\n" ); 
1 = wctomb( pmbnull, wc ); 
printf( "\tCharacters converted: %u\n", i ); 
printf( "\tMultibyte character: %.1s\n", pmbnull ); 

I 

Output Convert a wide character: 


Characters converted: 1 
Multibyte character: a 


Attempt to convert when target is NULL: 
Characters converted: @ 
Multibyte character: (null) 


Description 


Remarks 


Return Value 


Compatibility 


See Also 
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_wgetexit 


Returns a value that indicates how a QuickWin program will behave when the exit 
function is called. 


#include <io.h> 


int _ wgetexit( void ); 


QuickWin programs can optionally keep their windows on the screen after termi- 
nation. How a program will behave at exit time depends on its current exit be- 
havior setting. The _ wgetexit function lets you examine the current exit behavior 
setting. This routine is used only in QuickWin programs; it is not part of the 
Windows API. For full details about QuickWin, see Chapter 8 of Programming 
Techniques (in the Microsoft C/C++ version 7.0 documentation set). 


If the companion function _ wsetexit has been called previously, _ wgetexit 
returns the value that it set. This can be one of the following values: 


Value Meaning 
_WINEXITPROMPT Prompt the user at exit time to determine whether the 
windows stay on the screen 


_WINEXITNOPERSIST — The windows do not stay on the screen and there is no 
prompt to the user 


_WINEXITPERSIST The windows stay on the screen at exit 


If _ wsetexit has not been called previously, the _ wgetexit function returns 
_ WINEXITPERSIST, the default exit behavior. For a description of how to use 
this exit behavior, see _ wsetexit. 


If successful, _ wgetexit returns the current exit behavior setting value: 
_ WINEXITPROMPT, _ WINEXITNOPERSIST, or _WINEXITPERSIST. A 
return value of —1 indicates an error. 


Standards: None 

16-Bit: QWIN 

32-Bit: None 

_fwopen, _ wabout, _ wclose, _ wgetfocus, _ wgetscreenbuf, _ wgetsize, 


_wmenuclick, _ wopen, _ wsetexit, _ wsetfocus, _ wsetscreenbuf, _ wsetsize, 
_wyield 
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Example /* FWOPEN.C - Demonstrate opening QuickWin windows with _fwopen 
* Also demonstrate setting and getting exit behavior for QuickWin 
* / 


dHinclude <io.h> 
fHinclude <stdio.h> 


f}define OPENFLAGS "w" /* Access permission */ 

void main( void ) 

{ 
struct _wopeninfo wininfo; /* Open information */ 
char wintitle[32]="QuickWin "; /* Title for window */ 
FILE *wp; /* FILE ptr to window */ 
int nRes; /* 1/0 result */ 


/* Set up window info structure for _fwopen */ 
wininfo._version = _WINVER; 

wininfo._title = wintitle; 

wininfo._wbufsize = _WINBUFDEF; 


/* Check current ‘exit behavior’ setting */ 
/* Test should be true, since default is _WINEXITPERSIST */ 
/* So set new behavior to prompt user */ 
if( _wgetexit == _WINEXITPERSIST ) 
_wsetexit( _WINEXITPROMPT ); 


/* Create a new window */ 
/* NULL second argument accepts default size/position */ 
wp = _fwopen( &wininfo, NULL, OPENFLAGS ); 
if( wp == NULL ) 
{ 
printf( "***ERROR: _fwopen\n" ); 
exit( -1 ); 
} 


/* Write in the window */ 
nRes = fprintf( wp, “Hello, QuickWin!\n" ); 


/* Close the window */ 
nRes = fclose( wp ); 


/* On exiting anywhere, user is prompted 
* to keep window on screen or not 

* / 
exit( @ ); 


Description 


Remarks 


Return Value 
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_wgetfocus 


Gets a file handle to the currently active QuickWin window. 
#include <io.h> 


int _ wgetfocus( void ); 


The _ wgetfocus function determines which of a QuickWin program’s child (docu- 
ment) windows is active (has the program’s “focus”’). The routine returns the file 
handle of the active child window. If the entire application is not active, the 
routine returns the handle of the child window that would be active if the applica- 
tion were active. This routine is used only in QuickWin programs; it is not part of 
the Windows API. For full details about QuickWin, see Chapter 8 of Program- 
ming Techniques (in the Microsoft C/C++ version 7.0 documentation set). 


If the active window is a closed child window kept on the screen with the 
_WINPERSIST flag (see _ welose), _ wgetfocus fails. 


If successful, _ wgetfocus returns the file handle of the active child window. A re- 
turn value of —1 indicates an error. 


Compatibility Standards: None 
16-Bit: QWIN 
32-Bit: None 
See Also _fwopen, _ wabout, _ wclose, _ wgetexit, _ wgetscreenbuf, _ wgetsize, 


Example 


_ wmenuclick, _ wopen, _ wsetexit, _ wsetfocus, _ wsetscreenbuf, _ wsetsize, 
_wyield 


/* WGETFOC.C - Demonstrate testing which QuickWin window is the 
* active window with _wgetfocus 
* / 


d#Finclude <io.h> 
d#Hinclude <stdio.h> 


#t}define NUMWINS 4 /* Number of windows */ 
dtdefine OPENFLAGS "w" /* Access permission */ 
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void main( void ) 

{ 
int i, nRes; 
IMtrsT,. GF3 /* Set/Get focus results */ 
FILE *wins~NUMWINS]; /* Array of file pointers */ 


/* Open NUMWINS windows */ 
/* NULL arguments accept default characteristics */ 
for( i = @; i < NUMWINS; i++ ) 


{ 
winslLi] = _fwopen( NULL, NULL, OPENFLAGS ); 
if( winsCi] == NULL ) 
{ 
printf( "***ERROR: On _fwopen #%i\n", i ); 
exit( -1 ); 
} 
/* Write in each window */ 
nRes = fprintf( winsLi], "Windows!\n" ); 
} 


/* Tile child windows with _wmenuclick */ 
nRes = _wmenuclick( _WINTILE ); 
if( nRes == -1 ) 
i 
printf( "***ERROR: _wmenuclick\n" ); 
exit( -1 ); 
} 


/* Pass the focus from window to window */ 
for( i = @; i < NUMWINS; i++ ) 


{ 
Sf = _wsetfocus( _fileno( wins[i] ) ); 
gf = _wgetfocus(); 
if(( sf == -1 ) |] ( gf == -1 ) 
|| ( gf != _fileno( wins[i] ) ) ) 
printf( "***ERROR: _wsetfocus/_wgetfocus\n" ); 
exTit =1 >; 
} 
i 
nRes = _fcloseall(); 
exit( @ ); 


Description 


Remarks 


Return Value 


Compatibility 


See Also 
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_wgetscreenbuf 


Gets a QuickWin window’s current screen-buffer size. 
#include <io.h> 
long _ wgetscreenbuf( int wfh ); 


wth File handle to a Quick Win window 


The _ wgetscreenbuf function returns the size of a Quick Win window screen buff- 
er. This routine is used only in QuickWin programs; it is not part of the Windows 
API. For full details about Quick Win, see Chapter 8 of Programming Techniques 
(in the Microsoft C/C++ version 7.0 documentation set). 


Each Quick Win child window has a buffer in which the screen-display text for the 
window is stored. The buffer size determines how much text is retained and thus 
how much output can be viewed by scrolling back through the window. 


By default, the screen-buffer size is 2,048 bytes, but this value can be changed. 
See _ wsetscreenbuf. 


If successful, the _ wgetscreenbuf function returns the current screen-buffer size 
(in bytes) or the value__WINBUFINF. (A value of _WINBUFINF signifies that 
the size of the screen buffer is unlimited.) A return value of —1 indicates an error. 


Standards: None 
16-Bit: QWIN 
32-Bit: None 


_fwopen, _ wabout, _ wclose, _ wgetexit, _ wgetfocus, _ wgetsize,__wmenuclick, 
_wopen, _ wsetexit, _ wsetfocus, _ wsetscreenbuf, _ wsetsize, _ wyield 
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Example /* WGSCRBUF.C - Demonstrate examining the current size of a 
* QuickWin window's screen buffer 
* / 


4Ainclude <io.h> 
#Hinclude <stdio.h> 


4tdefine NUMWINS 4 /* Number of windows */ 
fKdefine OPENFLAGS "“w" /* Access permission */ 


void main( void ) 


{ 
int nSize; /* Size of screen buffer */ 
int nRes; /* Write result */ 
FILE *wp; /* File pointer */ 


/* Open a window */ 
/* NULL arguments accept default characteristics */ 
wp = _fwopen( NULL, NULL, OPENFLAGS ); 
if( wp == NULL ) 
i 
printf( "***ERROR:_fwopen\n" ); 
exit( -1 ); 
; | 


/* Get the size of its screen buffer */ 
nSize = _wgetscreenbuf( _fileno( wp ) ); 
nRes = fprintf( wp, "Screen buffer holds %i chars\n", nSize ); 


nRes = _wclose( _fileno( wp ), _WINPERSIST ); 


exit( @ ); 


_wgetsize 877 
_wgetsize 
Description Gets a Quick Win window’s current size and position on the screen. 
#include <io.h> 


int _ wgetsize( int wfh, int regtype, struct _ wsizeinfo *wsize ); 


wfh File handle to a QuickWin window 
reqtype Type of request 
wsize Pointer to a _ wsizeinfo structure 

Remarks The _ wgetsize function returns the size and position of the specified child 


window. This routine is used only in QuickWin programs; it is not part of the 
Windows API. For full details about Quick Win, see Chapter 8 of Programming 
Techniques (in the Microsoft C/C++ version 7.0 documentation set). 


The wfh argument is a handle to the window file. Use the manifest constant 
—_WINFRAMEHAND as the value of wfh to query the size and position of the 
parent frame (client or application window). The maximum size of the parent 
frame may vary according to the hardware specifications of your terminal. 


The reqtype argument is the type of request, which can have one of two values: 


Value Meaning 

_~WINCURRREQ Return the current size of the window 

_WINMAXKREQ Return the maximum size that the window can grow to 
(which cannot exceed the current size of the parent 
frame) 


The wsize argument is a pointer to a _ wsizeinfo structure (declared in IO.H) that 
returns the size and position information. The structure contains a _ type field that 
has one of the following values on return: 


Value Meaning 

_WINSIZEMIN Window is minimized 

_WINSIZEMAX Window is maximized 

_WINSIZECHAR Window is of the size specified in the structure’s 


remaining members 
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If the type returned is _WINSIZECHAR, the _x, _y, _h, and _ w values in the 
remainder of the structure specify the coordinates of the upper-left corner and the 
height and width of the window (in characters). Size returned always indicates the 
“client space” available in the parent frame, which means that it does not include 
space occupied by title bars and other parts of the window. 


Return Value If successful, _ wgetsize returns 0 and fills in the _ wsizeinfo structure. A return 
value of —1 indicates an error. 


Compatibility Standards: None 
16-Bit: QWIN 
32-Bit: None 
See Also _fwopen, _ wabout, _ wclose, _ wgetexit, _ wgetfocus, _ wgetscreenbuf, 
_ wmenuclick, _ wopen, _ wsetexit, _ wsetfocus, _ wsetscreenbuf, _ wsetsize, 
_wyield 


Example /* WGETSIZE.C - Demonstrate getting the 
* Size of a QuickWin window on the screen 
* / 


d#tinclude <io.h> 
fHinclude <stdio.h> 


#define OPENFLAGS "w" /* Access permission */ 
#define PERSISTFLAG _WINPERSIST /* Keep on screen */ 


void main( void ) 


{ 
int nRes; /* Result */ 
FILE *wp; /* File pointer */ 
struct _wsizeinfo ws; /* Size information */ 


/* Open a window */ | 
/* NULL arguments accept default characteristics */ 
wp = _fwopen( NULL, NULL, OPENFLAGS ); 
if( wp == NULL ) 
{ 
printf( "***kERROR:_fwopen\n" ); 
exitt =I.) 


/* Get the window's size and screen position */ 


ws._version = _WINVER; 
nRes = _wgetsize( _fileno( wp ), _WINCURRREQ, &ws ); 
if( nRes == -1 ) 
{ 

printf( "***ERROR: _wgetsize\n" ); 

a ag aie Came i 
i 
nRes = fprintf( wp, "Size:\n" ); 
nRes = fprintf( wp, " Upper Left: x = 4d\n", 
nRes = fprintf( wp, " y = 4d\n", 
nRes = fprintf( wp, ™ Width: w= 4d\n", 
nRes = fprintf( wp, " Height: h = 4d\n", 
nRes = _wclose( _fileno( wp ), PERSISTFLAG ); 


exit( @ ); 
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—_wmenuclick 
Description Chooses a Quick Win menu item. 
#include <io.h> 


int _ wmenuclick( int menuitem ); 


menuitem Constant specifying which menu command to 
execute 
Remarks The _ wmenuclick function emulates the user choosing a command from the 


QuickWin Window menu. This routine is used only in Quick Win programs; it is 
not part of the Windows API. For full details about QuickWin, see Chapter 8 of 
Programming Techniques (in the Microsoft C/C++ version 7.0 documentation set). 


The menuitem argument is a manifest constant specifying one of four available 
menu commands: | 


Value Meaning 

_WINTILE Tule the program’s child windows 

_ WINCASCADE Cascade the program’s child windows 

_ WINARRANGE Atrange icons at the bottom of the client window area 
_WINSTATBAR Toggle the status bar 


These are the only menu commands you can choose. Calling the function with one 
of these values performs the menu action. 


Return Value If successful, _ wmenuclick returns 0. A return value of —1 indicates an error. 
Compatibility Standards: None 

16-Bit: QWIN 

32-Bit: None 
See Also _fwopen, _ wabout, _ wclose, _ wgetexit, _ wgetfocus, _ wgetscreenbuf, 


_ Wwegetsize, _ wopen, _ wsetexit, _ wsetfocus, _ wsetscreenbuf, _ wsetsize 


Example /* WMENUCLK.C - Demonstrate choosing a menu 
* command with the QuickWin _wmenuclick function 
* / 


—_wmenuclick 


dFinclude <io.h> 
d#Finclude <stdio.h> 


#tdefine NUMWINS 4 /* Number of windows */ 
#tdefine OPENFLAGS "“w" /* Access permission */ 


void main( void ) 


{ 


int i, nRes; 

int wm; /* Menu click result */ 
Int-Sf;. af /* Set/Get focus results */ 
FILE *winsLNUMWINS]; /* Array of file pointers */ 


/* Open NUMWINS windows */ 
/* NULL arguments accept default characteristics */ 
for( i = 0; i < NUMWINS; i++ ) 


{ 
winslLi] = _fwopen( NULL, NULL, OPENFLAGS ); 
if( winslLi] == NULL ) 
{ 
printf( "***ERROR: On _fwopen #%i\n", 7 ); 
exit( -1 ); 
} 
/* Write in each window */ 
nRes = fprintf( winslLi], "Windows!\n" ); 
} 


/* Tile child windows with _wmenuclick */ 
wm = _wmenuclick( _WINTILE ); 
TEC Whi =1l. 9 
printf( "***ERROR: _wmenuclick\n" ); 
exit( -1 ); 
} 


/* Pass the focus from window to window */ 
for( i = 0; i < NUMWINS; i++ ) 


‘ 
sf = _wsetfocus( _fileno( wins[i] ) ); 
gf = _wgetfocus(); 
if(( sf == -1 ) || ( gf == -1 ) 
|| ( gf != _fileno( wins[i] ) ) ) 
printf( "***ERROR: _wsetfocus/_wgetfocus\n" ); 
Oxi ~=1. 
} 
} 
nRes = _fcloseall(); 
exit( @ ); 
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_wopen 

Description Opens a QuickWin window. 
#include <io.h> 


int _ wopen( struct _ wopeninfo *wopeninfo, 
struct _ wsizeinfo *wsizeinfo, int oflag ); 


wopeninfo Pointer to a _ wopeninfo structure 
wsizeinfo Pointer to a _ wsizeinfo structure 
oflag Type of operations allowed 
Remarks The _ wopen function opens a QuickWin window, returning a file handle to the 


window. This routine is used only in QuickWin programs; it is not part of the 
Windows API. For full details about QuickWin, see Chapter 8 of Programming 
Techniques (in the Microsoft C/C++ version 7.0 documentation set). 


The _ wopeninfo and _ wsizeinfo structures, declared in IO.H, are used to pass 
window initialization information, including the window’s initial size and position 
on the screen. You can pass NULL for the _ wsizeinfo argument to accept 
QuickWin size and positioning defaults, or you can declare a variable of type 
_wsizeinfo and fill in its fields with initial values. You must declare a variable 

of type _ wopeninfo and fill in its fields. 


For both the _ wopeninfo and _ wsizeinfo variables, set the _ version field to 
_WINVER, which is defined in IO.H. 


For the _ wopeninfo variable, assign a null-terminated string to the _title field con- 
taining the desired window title. You can also optionally set the size of the win- 
dow’s screen buffer in the _ wbufsize field. The default is 2,048 bytes, but you can 
pass some other number or the value __. WINBUFINF. The value _WINBUFINF 
imposes no limit on the buffer size. 


For the _ wsizeinfo variable, if you choose to pass size information, assign one of 
the following values to the _ type field: 


Value Meaning 
_WINSIZEMIN Minimize the window 
_WINSIZEMAX Maximize the window 


_WINSIZECHAR Use character coordinates for the window size 


Return Value 
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If the type is__ WINSIZECHAR, you must supply the _x, _y, _h, and _ w values 
in the remainder of the structure. They specify the upper-left corner and the height 
and width of the window (in characters). 


The _ wopen function is a low-level I/O call. It accepts the following access flags: 
_O_BINARY, _O_RDONLY, _O_ RDWR, _O_ TEXT, _O_ WRONLY. 


These flags can be combined with the bitwise-OR operator (| ). See _open for 
additional information about the flags. 


Unlike the _ open function, _ wopen does not accept the _O_ CREAT, 
_O_TRUNC, or _O_ EXCL flag. Using one of these flags results in an error. 


If successful, _ wopen returns a QuickWin file handle. A return value of —1 
indicates an error; errno is set to one of the following values: 


Value Meaning 

EINVAL An invalid oflag argument was given 

EMFILE No more file handles available (too many open files) 
Compatibility Standards: None 

16-Bit: QWIN 

32-Bit: None 


See Also 


Example 


_fwopen, _ wabout, _ wclose, _ wgetexit, _ wgetfocus, _ wgetscreenbuf, 
_weetsize, _ wmenuclick, _ wsetexit, _ wsetfocus, _ wsetscreenbuf, _ wsetsize, 
_wyield 


/* WOPEN.C - Demonstrate opening a QuickWin 
* window with _wopen 
a 


4#Ainclude <fcntl.h> 
#Finclude <io.h> 
#Finclude <stdio.h> 


#define PERSISTFLAG  _WINNOPERSIST 
#Fdefine OPENFLAGS _O_RDWR 
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_wopen 


void main( void ) 


{ 


int wth; /* File handle for window */ 
int nRes; /* Window write results */ 
struct _wopeninfo wininfo; /* Open information */ 


/* Set up window open information */ 
wininfo._version = _WINVER; 
wininfo._title = "Window Closing"; 
wininfo._wbufsize = _WINBUFDEF; 


/* Open a window with _wopen */ 
/* NULL second argument accepts default size */ 
wfh = _wopen( &wininfo, NULL, OPENFLAGS ); 
if( wfh == -1 ) 
{ 
printf( "***ERROR: On _wopen\n" ); 
exitG. Sh} 
} 


/* Write in the window */ 
nRes = write ( wfh, "Windows Everywhere! \n", 20 ); 


/* Close the window with _wclose */ 
nRes = _wclose( wfh, PERSISTFLAG ); 


exit( @ ); 


Description 


Remarks 


Return Value 


Compatibility 


See Also 


_wrapon 885 
_wrapon 
Controls word wrap. 
#include <graph.h> 
short __ far _wrapon( short option ); 


option Wrap condition 


The _ wrapon function controls whether text output with both the _ outmem and 

the _ outtext functions wraps to a new line or is simply clipped when the text out- 
put reaches the edge of the defined text window. The option argument can be one 
of the following manifest constants: 


Constant Meaning 
_GWRAPOFF Truncates lines at window border 
_GWRAPON Wraps lines at window border 


Note that this function does not affect the output of presentation-graphics routines 
or font routines. 


The function returns the previous value of option. There is no error return. 


Standards: None 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: None 


_outtext, _outmem, _scrolltextwindow, _ settextwindow 
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Example 


Output 


_wrapon 


/* WRAPON.C */ 


#Hinclude <conio.h> 
#Hinclude <graph.h> 


void main( void ) 
{ 
_wrapon( _GWRAPON ); 
while( !_kbhit() ) 
_outtext( "Wrap on! a 
_getch(); 
_outtext( "\n\n" ); 


_wrapon( _GWRAPOFF ); 
while( !_kbhit() ) 
_outtext( "Wrap off! " ); 
_getch(); 
_outtext( "\n\n" ); 


Wrap on! Wrap on! Wrap on! Wrap on! Wrap on! Wrap on! Wrap on! Wrap 
on! Wrap on! Wrap on! Wrap on! Wrap on! Wrap on! Wrap on! Wrap on! 
Wrap on! Wrap on! Wrap on! Wrap on! Wrap on! Wrap on! Wrap on! Wr 
ap on! Wrap on! Wrap on! Wrap on! Wrap on! Wrap on! Wrap on! Wrap o 
n! Wrap on! Wrap on! 


Wrap off! Wrap off! Wrap off! Wrap off! Wrap off! Wrap off! Wrap off! Wrap 


Description 


Remarks 


Return Value 
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_ write 


Writes data to a file. 
#include <io.h> Required only for function declarations 
int _ write( int handle, void *buffer, unsigned int count ); 


buffer Data to be written 


count Number of bytes 


The _ write function writes count bytes from buffer into the file associated with 
handle. The write operation begins at the current position of the file pointer (if 
any) associated with the given file. If the file is open for appending, the operation 
begins at the current end of the file. After the write operation, the file pointer is in- 
creased by the number of bytes actually written. 


The _ write function returns the number of bytes actually written. The return value 
may be positive but less than count (for example, when _ write runs out of disk 
space before count bytes are written). 


A return value of —1 indicates an error. In this case, errno is set to one of the fol- 
lowing values: 


Value Meaning 
EBADF Invalid file handle or file not opened for writing 
ENOSPC No space left on device 


For 16-bit platforms, if you are writing more than 32K (the maximum size for type 
int) to a file, the return value should be of type unsigned int. (See the example 
that follows.) However, the maximum number of bytes that can be written to a file 
at one time is 65,534, since 65,535 (or OXFFFF) is indistinguishable from —1 and 
would return an error. 


If the file is opened in text mode, each line-feed character is replaced with a 
carriage-return—line-feed pair in the output. The replacement does not affect the 
return value. 


When writing to files opened in text mode, the _ write function treats a CTRL+Z 
character as the logical end-of-file. When writing to a device, _ write treats a 
CTRL+Z character in the buffer as an output terminator. 
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Compatibility Standards: UNIX 
16-Bit: DOS, QWIN, WIN, WIN DLL 
32-Bit: DOS32X 


Use _ write for compatibility with ANSI naming conventions of non-ANSI func- 
tions. Use write and link with OLDNAMES.LIB for UNIX compatibility. 


See Also fwrite, _open, _ read 


Example /* WRITE.C: This program opens a file for output and uses _write to 
* write some bytes to the file. 
* / 


#Hinclude <io.h> 
fHinclude <stdio.h> 
#Hinclude <stdlib.h> 
#Hinclude <fcntl.h> 
#Finclude <sys\types.h> 
d#Finclude <sys\stat.h> 


char buffer[] = "This is a test of 'write' function"; 


void main( void ) 


{ 
int fh; 
unsigned byteswritten; 
if( (fh = _open( "write.o", _O_RDWR | _O_CREAT, 
_S_IREAD | _S_IWRITE )) != -1 ) 
{ 
if(( byteswritten = _write( fh, buffer, sizeof( buffer ))) == -1 ) 
perror( "Write failed" ); 
else 
printf( “Wrote Zu bytes to file\n", byteswritten ); 
_close( fh ); 
} 
} 


Output Wrote 35 bytes to file 


Description 


Remarks 


Return Value 
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_ wsetexit 


Specifies what a QuickWin application does when it exits (with a call to the exit 
function). 


#include <io.h> 
int _ wsetexit( int exb ); 


exb Desired exit behavior type 


QuickWin programs can optionally keep their windows on the screen after termi- 
nation. How a program behaves at exit time depends on its current exit behavior 
setting. The _ wsetexit function sets the exit behavior setting. This routine is used 
only in QuickWin programs; it is not part of the Windows API. For full details 
about Quick Win, see Chapter 8 of Programming Techniques (in the Microsoft 
C/C++ version 7.0 documentation set). 


The _ wsetexit function takes one of three arguments: 


Value Meaning 


_WINEXITPROMPT Prompt the user at exit time to determine whether the 
windows stay on the screen 

_WINEXITNOPERSIST — The windows do not stay on the screen and there is no 
prompt to the user 


_WINEXITPERSIST The windows stay on the screen at exit 


If _ WINEXITPERSIST is passed, or if _WINEXITPROMPT 1s passed and the 
user chooses to keep the windows on the screen, the windows stay visible, their 
contents can be copied and pasted, and their scroll bars can be used, but the win- 
dows are closed to further I/O. See _ welose. The default exit behavior is 
—WINEXITPERSIST if you do not call _ wsetexit. 


If successful, _ wsetexit returns 0. A return value of —1 indicates an error. 
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Compatibility Standards: None 
16-Bit: QWIN 
32-Bit: None 

See Also _fwopen, _ wabout, _ wclose, _ wgetexit, _ wgetfocus, _ wgetscreenbuf, 
_wegetsize, _wmenuclick, _ wopen, _ wsetfocus, _ wsetscreenbuf, _ wsetsize, 
_wyield 


Example /* FWOPEN.C - Demonstrate opening QuickWin windows with _fwopen 
* Also demonstrate setting and getting exit behavior for QuickWin 
* / 


#Hinclude <io.h> 
d4Ainclude <stdio.h> 


dtdefine OPENFLAGS “w" /* Access permission */ 

void main( void ) 

{ 
struct _wopeninfo wininfo; /* Open information */ 
char wintitle[32]="QuickWin "; /* Title for window */ 
FILE *wp; /* FILE ptr to window */ 
int nRes; /* 1/0 result */ 


/* Set up window info structure for _fwopen */ 
wininfo._version = _WINVER; 

wininfo._title = wintitle; 

wininfo._wbufsize = _WINBUFDEF; 


/* Check current ‘exit behavior" setting */ 
/* Test should be true, since default is _WINEXITPERSIST */ 
/* So set new behavior to prompt user */ 
if( _wgetexit == _WINEXITPERSIST ) 
_wsetexit( _WINEXITPROMPT ); 


/* Create a new window */ 
/* NULL second argument accepts default size/position */ 
wp = _fwopen( &wininfo, NULL, OPENFLAGS ); 
if( wp == NULL ) 
{ 
printf( "***ERROR: _fwopen\n" ); 
exit( -l1 ); 
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/* Write in the window */ 
nRes = fprintf( wp, "Hello, QuickWin!\n" ); 


/* Close the window */ 
nRes = fclose( wp ); 


/* On exiting anywhere, user is prompted 
* to keep window on screen or not 
* / 


exit( @ ); 
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_wsetfocus 


Description Makes a QuickWin window the active (focused) window. 
#include <io.h> 
int _ wsetfocus( int wfh ); 


wth File handle to a Quick Win window 


Remarks The _ wsetfocus function makes a QuickWin window the active window (sets the 
program ’s focus to the window). This routine is used only in Quick Win programs; 
itis not part of the Windows API. For full details about Quick Win, see Chapter 8 
of Programming Techniques (in the Microsoft C/C++ version 7.0 documentation 
set). 


If the application has focus, the window gets focus. If not, the window will get the 
focus when the application gets focus. 


If the program has other child windows, the focused window moves in front of 
them and is highlighted. This does not automatically direct I/O to the window. All 
I/O calls specify which window they are directed to by passing a stream pointer or 
file handle as an argument. 


Return Value If successful, _ wsetfocus returns 0. A return value of —1 indicates that the focus 
failed to change. 

Compatibility Standards: None 
16-Bit: QWIN 
32-Bit: None 

See Also _fwopen, _ wabout, _ wclose, _ wgetexit, _ wgetfocus, _ wgetscreenbuf, 
_ wegetsize, _wmenuclick, _ wopen, _ wsetexit, _ wsetscreenbuf, _ wsetsize, 
_wyield 


Example /* WSETFOC.C - Demonstrate making a new QuickWin window the active 
* window with _wsetfocus 
* / 


_wsetfocus 


d#Finclude <io.h> 
dFinclude <stdio.h> 


##tdefine NUMWINS 4 /* Number of windows */ 
deKdefine OPENFLAGS "w" /* Access permission */ 


void main( void ) 


{ 


int i, nRes; 
ING Sk OFS /* Set/Get focus results */ 
FILE *wins[~NUMWINS]; /* Array of file pointers */ 


/* Open NUMWINS windows */ 
/* NULL arguments accept default characteristics */ 
for( i = @; i < NUMWINS; i++ ) 
{ 
winslLi] = _fwopen( NULL, NULL, OPENFLAGS ); 
if( winslLi] == NULL ) 
{ 
printf( "***ERROR: On _fwopen #%i\n", i ); 
exit( -1 ); 
} 
/* Write in each window */ 
nRes = fprintf( winsli], "Windows!\n" ); 
} 


/* Tile child windows with _wmenuclick */ 
wm = _wmenuclick( _WINTILE ); 


if( wm == -1 ) 

{ 
printf( "***kERROR: _wmenuclick\n" ); 
exit( -1 ); 

} 


/* Pass the focus from window to window x*/ 
for( i = 0; i < NUMWINS; i++ ) 


{ 
Sf = _wsetfocus( _fileno( wins[i] ) ); 
gf = _wgetfocus(); 
if(( sf == -1 ) || ( gf == -1 ) 
|| ( gf != _fileno( wins[i] ) ) ) 
printf( "***ERROR: _wsetfocus/_wgetfocus\n" ); 
exit( -1 ); 
i 
} 
nRes = _fcloseall(); 
exit( @ ); 
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Description 


Remarks 


Return Value 


Compatibility 


See Also 


_wsetscreenbuf 


Sets a Quick Win window’s screen-buffer size. 
#include <io.h> 


int _ wsetscreenbuf( int wfh, long bufsiz ); 


wfh File handle to a QuickWin window 
bufsiz Desired size of the window’s screen buffer (in 
bytes) 


The _ wsetscreenbuf function sets the size of a QuickWin window’s screen buffer 
to bufsiz bytes. This size determines how much text is retained in the buffer and 
thus how much text you can scroll back through. This routine 1s used only in 
QuickWin programs; it is not part of the Windows API. For full details about 
Quick Win, see Chapter 8 of Programming Techniques (in the Microsoft C/C++ 
version 7.0 documentation set). 


The bufsiz argument can be specified as a number or as one of the following 
values: 


Value Meaning 
_ WINBUFDEF Use the default window screen-buffer size (2,048 bytes) 
_ WINBUFINF Use a window screen buffer of unlimited size 


The buffer size simply limits how big the buffer can become. The buffer is always 
allocated dynamically, so that it fits its contents. Specifying _WINBUFINF puts 
no upper limit on buffer size. The buffer may grow within the limits of available 
memory. 


If successful, _ wsetscreenbuf returns 0. A return value of —1 indicates an error. 


Standards: None 
16-Bit: QWIN 
32-Bit: None 


_fwopen, _ wabout, _ wclose, _ wgetexit, _ wgetfocus, _ wgetscreenbuf, 
_weetsize, _wmenuclick, _ wopen, _ wsetexit, _ wsetfocus, _ wsetsize 


Example 


_wsetscreenbuf 


/* WSSCRBUF.C - Demonstrate setting the size of a QuickWin window's 
* screen buffer 

* Note: The size is set here to an amount smaller than the default 
* size, but you can set it larger as well 

* / 


#Hinclude <io.h> 
4#FAinclude <stdio.h> 


dtdefine NUMWINS 4 /* Number of windows */ 
ftdefine OPENFLAGS  “w" /* Access permission */ 
dtdefine NUMLINES 100 /* Lines of text to write */ 
void main( void ) 
{ 

ING. Is /* Loop variable */ 

int nSize; /* Old size of screen buffer */ 

int nWinBufSize = 15@@L; /* New size */ 

int nRes; /* Result */ 

FILE *wp; /* File pointer */ 


/* Open a window */ 
/* NULL arguments accept default characteristics */ 
wp = _fwopen( NULL, NULL, OPENFLAGS ); 
if( wp == NULL ) 
{ 
printf( "***ERROR: fwopen\n" ); 
exit( -1 ); 
J 


/* Get the size of its screen buffer */ 
nSize = _wgetscreenbuf( _fileno( wp ) ); 
nRes = fprintf( wp, “Screen buffer holds %i chars\n", nSize ); 


/* Reset the screen buffer size */ 
nRes = _wsetscreenbuf( _fileno( wp ), nWinBufSize ); 


/* Write many lines in the window */ 
for( i = 0; i < NUMLINES; i++ ) 


: nRes = fprintf( wp, "%i Windows!\n", i ); 

ane = fprintf( wp, "\nWhen the program ends, click "No'\n" ); 
nRes = fprintf( wp, "and try using the scroll bars\n" ); 

nRes = _wclose( _fileno( wp ), _WINPERSIST ); 

exit( @ ); 
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Description 


Remarks 


Return Value 


Compatibility 


_ wsetsize 


Sets the size and screen position of a QuickWin window. 
#include <io.h> 
int _ wsetsize( int wfh, struct _ wsizeinfo *wsize ); 


with File handle to a Quick Win window 


wsize Pointer to a _ wsizeinfo structure 


The _ wsetsize function sets the size and position of a Quick Win window. This 
routine is used only in QuickWin programs; it is not part of the Windows API. For 
full details about QuickWin, see Chapter 8 of Programming Techniques (in the 
Microsoft C/C++ version 7.0 documentation set). 


The wsize argument points to a __ wsizeinfo structure (declared in IO.H) containing 
the new size and position information. The structure contains a _ type field that 
can have one of the following values: 


Value Meaning 

_WINSIZEMIN Minimize the window 

_WINSIZEMAX Maximize the window 

_ WINSIZRESTORE Restore a previously minimized window 
_WINSIZECHAR Use character coordinates for the window size 


If the type is_ WINSIZECHAR, you must supply the _x, _y, _h, and _w values 
in the remainder of the structure. They specify the upper-left corner and the height 
and width of the window (in characters). 


If successful, _ wsetsize returns 0. A return value of —1 indicates an error. 


Standards: None 
16-Bit: QWIN 
32-Bit: None 


See Also 


Example 


_wsetsize 


_fwopen, _ wabout, _ wclose, _ wgetexit, _ wgetfocus, _ wgetscreenbuf, 
_weetsize, _wmenuclick, _ wopen, _ wsetexit, _ wsetfocus, _ wsetscreenbuf, 
_wyield 


/* WSETSIZE.C - Demonstrate setting the 
* Size of a QuickWin window on the screen 
* / 


#Hinclude <io.h> 
dHinclude <stdio.h> 


dtdefine OPENFLAGS "Ww" /* Access permission */ 
#fdefine PERSISTFLAG _WINPERSIST /* Keep on screen */ 


void main( void ) 


{ 
int nRes; /* Result */ 
FILE *wp; /* File pointer */ 
struct _wsizeinfo ws; /* Size information */ 


/* Open a window */ 
/* NULL arguments accept default characteristics */ 
wp = _fwopen( NULL, NULL, OPENFLAGS ); 
if( wp == NULL ) 
{ 
printf( "***ERROR:_fwopen\n" ); 
exit( -1 ); 
} 


/* Minimize the window to an icon */ 
ws._version = _WINVER; 
ws._type = _WINSIZEMIN; 


nRes = _wsetsize( _fileno( wp ), &ws ); 
Trt. WRes: ==). 
{ 
printf( "***ERROR: _wsetsize\n" ); 
exit( -1l ); 
} 


nRes = _wclose( _fileno( wp ), PERSISTFLAG ); 


exit( @ ); 
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Description 


Remarks 


Return Value 


Compatibility 


See Also 


_wyield 


Yields processor control from a Quick Win program for Windows queue servicing. 
#include <io.h> 


void _ wyield( void ); 


The _ wyield function yields control to Windows in order to give processor time to 
other Windows applications. This routine is used only in QuickWin programs; it is 
not part of the Windows API. For full details about Quick Win, see Chapter 8 of 

Programming Techniques (in the Microsoft C/C++ version 7.0 documentation set). 


A Windows application must service its message queue periodically to ensure 
smooth appearance and performance. Well-behaved QuickWin applications yield 
time to other applications and allow the user to switch tasks without having to wait 
for the Quick Win program to complete lengthy processing. 


The compiler attempts to issue “yield for queue servicing” calls at appropriate 
times. But in some cases a program requires additional yield calls, particularly 
during lengthy processing loops. If Windows appears sluggish when running a 
Quick Win program, insert _ wyield calls into the program to improve Windows’ 
responsiveness. Note that when an application is servicing the message queue 
(yielding) it can be told to stop so the user can work with another running Win- 
dows application. 


None. 


Standards: None 

16-Bit: QWIN 

32-Bit: None 

_fwopen, _ wabout, _ wclose, _ wgetexit, _ wgetfocus, _ wgetscreenbuf, 


_ wegetsize, _wmenuclick, _ wopen, _ wsetexit, _ wsetfocus, _ wsetscreenbuf, 
_wsetsize 


Example 


_wyield 


/* WYTELD.C - Demonstrate yielding processor time from a 
* QuickWin program so that other Windows programs can 
* process their message queues; uses _wyield 
a / 

#Hinclude <io.h> 

void compute( int a ); /* Function prototype */ 


void main( void ) 


{ 
int 1; 
for( 1 = @; 1 <= 10000; 1++ ) 
{ 
compute( 1 ); /* Time-consuming function you supply */ 
if( 1% 1000 ) 
_wyield(); /* Yield once every 1000 loops */ 
} 
} 


void compute( int a ) 
{ 
/* Intensive computations */ 


} 
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Index 


A 


abort function, 76—77 
Aborting 
abort function, 76—77 
assert function, 92—93 
abs function, 78-79 
Absolute value, calculating, 78—79 
_access function, 80-8 1 
Accessing variable-argument lists, va_arg, va_end 
and va_start functions, 836-839 
acos function, 82—83 
_acosl function, 82—83 
Adding memory to heaps, 
_heapadd functions, 406—409 
_alloca function, 84—85 
Allocating memory 
_alloca function, 84-85 
arrays, calloc functions, 131—132 
blocks 
_dos_allocmem function, 183-184 
_halloc function, 400-401 
malloc functions, 479-482 
freeing huge memory blocks, _hfree function, 
422-423 
heaps, _bheapseg function, 107—109 


virtual memory blocks, _vmalloc function, 857—858 


_amblksize variable, 61 
Analyzing 
pie chart data, pg analyzepie function, 552 
scatter chart data, pg analyzescatter functions, 
553-554 


series of data, _pg_analyzechart functions, 549-551 


ANSI compatibility, x 
Appending 
characters of strings, strncat and _fstrncat 
functions, 765—766 
strings, strcat and _fstrcat functions, 738—739 
_arc function, 86—87 
_arc_w function, 86—87 
_arc_wxy function, 86—87 
Arccosines, calculating, acos functions, 82—83 


Arcs 
determining viewpoint coordinate endpoints, 
_getarcinfo function, 344 
drawing, _arc functions, 86—87 
Arcsines, calculating, asin functions, 90-91 
Arctangents, calculating, atan functions, 94—95 
Argument lists, variable length, 59 
Arguments 
floating-point, calculating, fabs and _fabsl 
functions, 258—259 
type checking, x, 8 
variable, accessing lists, va_arg, va_end and 
va_start functions, 836-839 
Arrays 
searching, bsearch function, 127—128 
sorting, qsort function, 605-606 
using huge, with library functions, 16 
asctime function, 88—89 
asin functions, 90-91 
_asinl function, 90-91 
assert function, 92—93 
atan function, 94—95 
atan? function, 94—95 
_atan21 function, 94—95 
_atanl function, 94—95 
atexit function, 96—97 
atof function, 98-100 
atoi function, 98—100 
atol function, 98—100 
_atold function, 98—100 


Background colors 

getting, _getbkcolor function, 345 

setting current, _setbkcolor function, 652-653 
_bcalloc function, 131-132 
_bdos function, 101-102 
Bessel functions, 103—105 
_bexpand function, 255-257 
_bfree function, 306-308 
_bfreeseg function, 106 
_bheapadd function, 406—409 
_bheapchk function, 410-412 
_bheapmin function, 413-414 
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_bheapseg function, 107—109 
_bheapset function, 415-417 
_bheapwalk function, 418-421 
BIOS 
calling time and date services, 
_bios_timeofday function, 125-126 
communications services, _bios_serialcom 
function, 122—124 
disk services, _bios_disk function, 110-113 
equipment-list service, _bios_equiplist function, 
114-115 
interface services routines, 55 
keyboard services, _bios_keybrd function, 116—118 
memory-size service, _bios_memsize function, 119 
printer services, _bios_printer function, 120-121 
_bios_disk function, 110-113 
_bios_equiplist function, 114-115 
_bios_keybrd function, 116-118 
_bios_memsize function, 119 
_bios_printer function, 120-121 
_bios_serialcom function, 122—124 
_bios_timeofday function, 125—126 
Bitmaps 
getting characters, pg getchardef function, 564 
setting characters, _pg_setchardef function, 573 
Bits, rotating 
_lrotl and _lrotr functions, 468 
_rotl and _rotr functions, 633-634 
_bmalloc function, 479-482 
Bold type, use of, xiv 
Books of interest, xii 
Brackets, double, use of, xv 
Braces, document conventions, xv 
_brealloc function, 613-615 
bsearch function, 127—128 
Buffer-manipulation routines (list), 18 
Buffers 
committing contents to disk, 37 
controlling, setting size, setvbuf function, 688-689 
moving one to another, memmove and 
_fmemmove functions, 510-512 
Quick Win, getting screen buffer size, 
_wegetscreenbuf function, 875-876 
setting to specified character, memset and 
_fmemset functions, 513-514 
Stream control, setbuf function, 654-655 
writing to files, _dos_write function, 232—233 
Bytes 
inputting from port, _inp and _inpw functions, 428 
locking, unlocking, _locking function, 460-462 


Bytes (continued) 


outputting at port, _outp and 
_outpw functions, 542-544 
swapping, _swab function, 801-802 


_cabs function, 129-130 
_cabsl function, 129-130 
Calculating 


absolute value 
arguments, abs function, 78-79 
complex numbers, _cabs and _cabsl functions, 
129-130 
floating point arguments, fabs and _fabsl 
functions, 258—259 
long integers, labs function, 445-446 
arccosines, acos functions, 82—83 
arcsines, asin functions, 90-91 
arctangents, atan functions, 94—95 
ceilings of values, ceil and _ceill functions, 
133-134 
cosines, cos functions, 163—164 
exponentials, exp and _expl functions, 253-254 
floating-point remainders, fmod and _fmod1 
functions, 288—289 
floors of values, floor and _floorl functions, 
285-286 
hypotenuses, _hypot and _hypotl functions, 
424-425 
logarithms, log functions, 463-464 
square roots, sqrt and _sqrtl functions, 727-728 
tangents, tan functions, 805-806 
time used by calling process, clock function, 
154-155 


Calling 


BIOS 
communications services, _bios_serialcom 
function, 122—124 : 
disk services, _bios_disk function, 110-113 
equipment-list service, _bios_equiplist function, 
114-115 
keyboard services, _bios_keybrd function, 116-118 
memory-size service, _bios_memsize function, 119 
printer services, _bios_printer function, 120-121 
time and date services, _bios_timeofday function, 
125-126 
library routines, 5—6 
processes, terminating, exit and _exit functions, 
251-252 


calloc functions, 131—132 


Capital letters, small, document conventions, xv 
Case sensitivity, operating systems, 9 
ceil function, 133-134 
_ceill function, 133-134 
_cexit function, 135 
_cgets function, 136—137 
_chain_intr function, 138—139 
Chaining interrupts between handlers, _chain_intr 
function, 138-139 
Changing 
current drives, _chdir function, 142—143 
directories, _chdir function, 140-141 
file size, _chsize function, 146—147 
file-permission settings, chmod function, 144-145 
font text output orientation 
_getgtextvector function, 366 
_setgtextvector function, 665 
memory 
block size, _expand functions, 255—257 
segment size, __dos_setblock function, 216-217 
Character classification and conversion functions 
(list), 19 
Character devices, checking, _isatty function, 441 
Character sets, scanning strings for characters, 
strpbrk and _fstrpbrk functions, 776-777 
Character strings, getting from console, _cgets 
function, 136—137 
Character-font functions, 22 
Characters 
appending from strings, strncat and _fstrncat 
functions, 765—766 
comparing 
from two strings, strncmp and _fstrncmp functions, 
767-769 
in two buffers, case-sensitive, _memicmp and 
_fmemicmp functions, 506—507 
in two buffers, memcmp and 
_fmemecmp functions, 500-502 
of two strings, _strnicmp and _fstrnicmp functions, 
772-773 
converting 
between uppercase and lowercase, 19 
multibyte to wide, mbtowc and _fmbtowc 
functions, 491-493 
series of wide to multibyte, wcstombs and 
_fwestombs functions, 867-868 
to uppercase, lowercase, ASCII, 817-819 
wide to multibyte, wctomb and _fwctomb 
functions, 869-870 
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Characters (continued) 
copying 
between buffers, memcpy and _fmemcpy 
functions, 503-505 
from buffers, memccpy and _fmemccpy 
functions, 496-497 
finding 
in buffers, memchr and _fmemchr functions, 
498-499 
in strings, strchr and _fstrchr functions, 740—742 
formatting and printing to console, _cprintf 
function, 165—166 
getting from console, _getch and _getche 
functions, 348-349 
getting pixel bitmaps for specified characters, 
_pg_getchardef function, 564 
moving to another segment, _movedata function, 
525-526 
multibyte 
converting to wide, mbstowcs and _fmbstowcs 
functions, 489-490 
getting length, determining validity, mblen and 
_fmblen functions, 487-488 
of a string, initializing to given characters, _strnset 
and _fstrnset functions, 774-775 
pixel bitmaps, setting, pg setchardef function, 573 
pushing back 
last read from console, _ungetch function, 829-830 
onto streams, ungetc function, 827-828 
reading from streams 
fgetc and _fgetchar functions, 273-274 
getc and getchar functions, 346—347 
reversing in strings, _strrev and _fstrrev functions, 
780-781 
scanning strings 
for last occurrence, strrchr and _ fstrrchr functions, 
778-179 
for specified character sets, strpbrk and _fstrpbrk 
functions, 776-777 
setting 
buffers to specified, memset and _fmemset 
functions, 513-514 
characters in strings to, _strset and _fstrset 
functions, 782—783 
testing 
for specified conditions, is functions, 437-440 
individual, 19 
writing 
to console, _putch function, 595-596 
to streams, fputc and _fputchar functions, 301-302 
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Charts 
displaying 
pie, _pg_chartpie function, 558-559 


series or multiseries, pg chart functions, 555-557 


initializing environment, _pg_defaultchart 
function, 562-563 
presentation-graphics, 30 
scatter. See Scatter charts 
_chdir function, 140-141 
_chdrive function, 142—143 
Checking 
character device, _isatty function, 441 
console for keyboard input, _kbhit function, 444 
heaps, _heapset functions, 415-417 
Child processes 
creating, executing, _spawn functions, 717-722 
defined, 51 
loading and executing, _exec functions, 246—250 
_chmod function, 144-145 
Choosing 
between functions and macros, 9—11 
QuickWin menu items, _wmenuclick function, 
880-88 1 
_chsize function, 146—147 
Cleanup operations during process, _cexit and 
_c_exit functions, 135 
_clear87 function, 148-149 
clearerr function, 150-151 
Clearing 
floating-point status word, _clear87 function, 
148-149 
screen area, clearscreen function, 152—153 
_clearscreen function, 152—153 
clock function, 154-155 
_close function, 156—157 
Closing 
files 
_close function, 156—157 
_dos_close function, 185—186 
streams, fclose and _fcloseall functions, 260—261 
Colors 
background 
getting, _getbkcolor function, 345 
setting current, _setbkcolor function, 652-653 
filling display area with, _floodfill and 
_floodfill_w functions, 283—284 
getting current text, _gettextcolor function, 378 
getting current, _getcolor function, 350-351 
getting pixel values, _getpixel functions, 374-375 


Colors (continued) 
palettes 
See also Palettes 
getting, pg getpalette function, 565-567 
remapping, _remapallpalette and _remappalette 
functions, 619-623 
setting 
current text, _settextcolor function, 678—680 
current, _setcolor function, 658-659 
low-level palette routines, 25 
pixel to current, _setpixel functions, 676-677 
Commands 
executing, system function, 803-804 
optional items, xv 


_commit function, 158—159 


Committing to disk, _dos_commit function, 
187-188 
Communications services, calling BIOS, 
_bios_serialcom function, 122-124 
COMMODE.OBJ, 33, 37 
Comparing 
characters in two buffers 
memcmp and _fmemcmp functions, 500-502 
_memicmp and _fmemicmp functions, 506-507 
characters of two strings 
strncmp and _fstrncmp functions, 767-769 
_strnicmp and _fstrnicmp functions, 772-773 
strings 
lowercase, _stricmp and _fstricmp functions, 
759-760 
null-terminated, strcmp and _fstrcmp functions, 
743-745 
using locale-specific information, strcoll function, 
746 
Compatibility, 75 
Computing 
Bessel functions, 103-105 
quotients and remainders 
from long integers, Idiv and Idiv_t functions, 
449-450 
of two integer values, div function, 181-182 
real numbers from mantissa and exponent, ldexp 
and _Idexpl functions, 447-448 
Consistency checking of heaps, _heapchk 
functions, 410-412 
Console 
checking for keyboard input, _kbhit function, 444 
getting characters from 
_cgets function, 136—137 
_getch and _ getche functions, 348-349 
I/O routines, 43-44 


Console (continued) 
putting strings to, _cputs function, 167 
reading data from, _cscanf function, 171-172 
writing characters to, _putch function, 595-596 
_control87 function, 160—162 


Controlling 
stream buffering, buffer size, setvbuf function, 
688-689 
word wrap, _wrapon function, 885-886 
Converting 


between IEEE and MS double values, 
_dieeetomsbin and _dmsbintoieee functions, 
175 
characters to ASCII, lower- or uppercase, 
__toascii, tolower, toupper functions, 817-819 
double numbers to strings, _ecvt function, 239-240 
floating-point 
numbers between IEEE and Microsoft binary 
format, _fieeetomsbin and _fmsbintoieee 
functions, 279 
numbers to strings, _fcvt function, 262—263 
values to strings, _gcvt function, 340-341 
integers 
long to strings, _ltoa function, 474-475 
to strings, _itoa function, 442-443 
unsigned long to strings, _ultoa function, 823-824 
multibyte to wide characters, mbstowcs and 
_fmbstowcs functions, 489-490 
single multibyte to wide characters, mbtowc and 
_fmbtowc functions, 491-493 
strings 
to double-precision or long-integer values, strtod, 
strtol, _strtold and strtoul functions, 790-793 
to lowercase, _strlwr and _fstrlwr functions, 


763-764 

to uppercase, _strupr and _fstrupr functions, 
797-7198 

to values, atof, atoi, atol and _atold functions, 
98-100 


time 
local to calendar, mktime function, 521-522 
structures to character strings, asctime function, 
88-89 
to character strings, ctime function, 173-174 
values to structures, gmtime function, 394-395 
values with zone correction, localtime function, 
458—459 
wide to multibyte characters 
wcestombs and _fwcstombs functions, 867—868 
wctomb and _fwctomb functions, 869-870 
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Coordinates 
translating to view, _getviewcoord functions, 
386-387 
translating views to window coordinates, 
_getwindowcoord function, 39] 
Copying 
characters 
between buffers, memcpy and _fmemcpy 
functions, 503-505 
from buffers, _memccpy and _fmemccpy 
functions, 496—497 
dates to buffers, _strdate function, 751—752 
strings, strcpy _fstrcpy functions, 747-748 
time to buffers, _strtime function, 788—789 
cos function, 163-164 
cosh function, 163—164 
_coshl function, 163—164 
Cosines, calculating, cos functions, 163-164 
_cosl function, 163-164 
_cprintf function, 165-166 
_cpumode variable, 65 
_cputs function, 167 
_creat function, 168—170 
Creating 
directories, mkdir function, 516—517 
environment variables, _putenv function, 597-599 
file handles, dup and _dup2 functions, 236-238 
filenames 
temporary, _tempnam and tmpnam functions, 
809-811 
unique, _mktemp function, 518—520 
files 
_creat function, 168-170 
_dos_creat functions, 189-190 
temporary, tmpfile function, 815-816 
graphics output, 26-27 
new child process, _spawn functions, 717-722 
path names, _makepath function, 476-478 
text windows, _settextwindow function, 687 
viewports, _setviewport function, 699-700 
_cscanf function, 171-172 
CSTARTUP.BAT, 42 
ctime function, 173—174 
Cursors 
setting attributes, _settextcursor function, 681-682 
setting toggle for graphics, _displaycursor function, 
179-180 


Data 
analyzing series of, pg analyzechart functions, 
549-551 
reading from files, _read function, 611-612 
Data-conversion routines, 20 
Date 
copying to buffers, _strdate function, 751-752 
getting date file written, _dos_getftime function, 
204—206 
setting for files, _dos_setftime function, 224—226 
system 
getting, dos_getdate function, 196-197 
setting, dos_setdate function, 218-219 
daylight variable, 62 
Deallocating 
memory blocks, free functions, 306-308 
virtual memory blocks, _vfree function, 844 
Debugging heap-related problems 
_heapchk functions, 410-412 
_heapset functions, 415-417 
_heapwalk functions, 418-421 
Defining locales, setlocale function, 668-669 
Deleting files 
specified by filename, remove function, 624 
specified by path, _unlink function, 831-832 
_dieeetomsbin function, 175 
difftime function, 176—177 
Directories 
creating, mkdir function, 516-517 
current 
changing, _chdir function, 140-141 
getting attributes, _dos_getfileattr function, 
202-203 
getting path names, _getdcwd function, 356-358 
getting, _getcwd function, 354-355 
removing, _rmdir function, 629-630 
renaming, rename function, 625-626 
setting attributes, dos_setfileattr function, 222—223 
subdirectory conventions, 9 
Directory-control routines, 20 
_disable function, 178 
Disabling interrupts, _ disable function, 178 
Disk drives, getting current 
_dos_getdrive function, 200—201 
_getdrive function, 359 
Disk services, calling BIOS, _bios_disk 
function, 110-113 
Disks, getting information, _dos_getdiskfree 
function, 198-199 


_displaycursor function, 179-180 
Displaying charts 
pie, _pg_chartpie function, 558-559 
scatter, pg chartscatter functions, 560-561 
single or multiseries, pg chart functions, 555-557 
div function, 181-182 
Dividing integers, div function, 181-182 
_dmsbintoieee function, 175 
Document conventions, xiv 
DOS 
compatibility, xi 
defined, xv 
interface routines 
described, 58 
(list), 56-57 
system calls 
_bdos function, 101—102 
_intdos function, 433—434 
_intdosx function, 435-436 
DOS Extender described, xi 
_dos_allocmem function, 183-184 
_dos_close function, 185—186 
_dos_commit function, 187-188 
_dos_creat function, 189-190 
_dos_creatnew function, 189-190 
_dos_find function, 191-193 
_dos_findfirst function, 191-193 
_dos_findnext function, 191—193 
_dos_freemem function, 194—195 
_dos_ getdate function, 196-197 
_dos_getdiskfree function, 198-199 
_dos_getdrive function, 200-201 
_dos_getfileattr function, 202—203 
_dos_getftime function, 204—206 
_dos_gettime function, 207—208 
_dos_getvect function, 209 
_dos_keep function, 210-211 
_dos_open function, 212-213 
_dos_read function, 214—215 
_dos_setblock function, 216—217 
_dos_setdate function, 218—219 
_dos_setdrive function, 220-221 
_dos_setfileattr function, 222—223 
_dos_setftime function, 224—226 
_dos_settime function, 227—228 
_dos_setvect function, 229—231 
_dos_write function, 232—233 
_doserrno variable, 63-64 
_dosexterr function, 234—235 


Drawing 
elliptical arcs, _arc functions, 86—87 
ellipses, _ellipse functions, 241-242 
lines 
getting mode, _getwritemode function, 392-393 
to points, _lineto functions, 453-454 
polygons, _polygon functions, 580-582 
rectangles, rectangle functions, 616-617 
wedge-shaped figures, _pie functions, 577-579 
Drives 
changing current, _chdir function, 142—143 
default, setting, _dos_setdrive function, 220-221 
getting current 
_dos_getdrive function, 200-201 
_getdrive function, 359 
_dup function, 236-238 
_dup2 function, 236-238 
Duplicating strings, _strdup functions, 753-754 


E 


_ecvt function, 239-240 
_ellipse function, 241—242 
_ellipse_w function, 241-242 
_ellipse_wxy function, 241-242 
Ellipses, drawing, _ ellipse functions, 241-242 
Ellipsis, document conventions, xv 
Elliptical arcs, drawing, _arc functions, 86—87 
_enable function, 243 
Enabling interrupts, _enable function, 243 
environ variable, 66 
Environment 
control functions, 49—52 
creating variables, _putenv function, 597-599 
table, getting value from, getenv function, 360-361 
time, setting, _tzset function, 820-822 
_eof function, 244—245 
ermo variable, 63-64 
Error handling 
critical conditions, _hard functions, 402—405 
math 
_matherr and _matherrl functions, 483-485 
routines, 13 
stream I/O, 13 
transferring control to handler, _set_new_handler 
functions, 672—675 
using, 12—13 
Error messages 
getting, printing, strerror and _strerror functions, 
755-756 
printing, perror function, 547-548 
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Errors 
getting information, _dosexterr function, 234—235 
messages. See Error messages 
testing on streams, ferror function, 269-270 
_exec functions, 246—250 
_execl function, 246—250 
_execle function, 246—250 
_execlp function, 246-250 
_execlpe function, 246-250 
Executing 
8086 interrupts, accepting segment-register values, 
_int86x function, 431-432 
8086-processor-family interrupt, _1nt86 function, 
429-430 
commands, system function, 803-804 
DOS system calls 
_intdos function, 433-434 
_intdosx function, 435—436 
new child process, _spawn functions, 717-722 
_execv function, 246—250 
Exit 
processing function at, atexit and _fatexit 
functions, 96-97 
QuickWin applications, specifying, _wsetexit 
function, 889-891 
registering routine to be called at, _fonexit 
and_onexit functions, 531-532 
exit function, 251-252 
Exiting Quick Win applications, getting value, 
_weetexit function, 871-872 
exp function, 253-254 
_expand function, 255-257 
_expl function, 253-254 
Exponential functions, calculating powers, 
pow functions, 583-584 
Exponentials, calculating, exp and _exp! functions, 
253-254 


F 


fabs function, 258—259 
_fabsl function, 258—259 
far functions, use, 18 
_fatexit function, 96-97 
_fcalloc function, 131-132 
fclose function, 260-261 
_fcloseall function, 260-261 
_fevt function, 262-263 
_fdopen function, 264—266 
feof function, 267—268 
ferror function, 269-270 
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_fexpand function, 255-257 
fflush function, 271—272 
_ffree function, 306-308 
_fgetchar function, 273-274 
fgetpos function, 275-276 
fgets function, 273-274, 277-278 
_fheapchk function, 410-412 
_fheapmin function, 413-414 
_fheapset function, 415—417 
_fheapwalk function, 418-421 
_fieeetomsbin function, 279 


File handles 
closing QuickWin window’s, _wclose function, 
865—866 
creating, reassigning, dup and _dup2 functions, 
236-238 


getting, _fileno function, 282 
increasing maximum number, 40-41 
low-level I/O (list), 40 
QuickWin Window, _wegetfocus function, 
873-874 
predefined, 40 
File pointers 
defined, 37 
getting position 


associated with handle, _ tell function, 807-808 
associated with stream, ftell function, 329—330 


current, ftell function, 329—330 
moving 


associated with handle, _Iseek function, 471-473 
associated with stream, fseek function, 318—320 


reassigning, freopen function, 311-313 
repositioning, rewind function, 627-628 
File sharing, opening stream with, _fsopen 
function, 323-325 
File streams, opening for Quick Win window, 
_fwopen function, 335-337 
File-access permission, _access function, 80-81 
File-handling routines, 21 
File-permission settings, changing, _chmod 
function, 144-145 
File-position indicators, getting from streams, 
fgetpos function, 275-276 
_filelength function, 280-281 
Filenames 
creating 
temporary, _tempnam and tmpnam functions, 
809-811 
unique, _mktemp function, 518-520 
operating system conventions, 8—9 
_fileno function, 282 


Files 


accessing, permission for, _access function, 80-81 
attributes, current, dos_getfileattr function, 
202-203 
changing size, _chsize function, 146-147 
closing 
_close function, 156-157 
_dos_close function, 185—186 
for I/O, 40 
creating 
_creat function, 168—170 
_dos_creat functions, 189-190 
date and time written, _dos_getftime function, 
204—206 
deleting 
specified by filename, remove function, 624 
specified by path, _unlink function, 831-832 
end-of-file testing, 13 
finding, _dos_find functions, 191—193 
flushing to disk 
_commit function, 158-159 
COMMODE.OBJ, 33, 37 
_dos_commit function, 187—188 
_fdopen function 264—266 
_fopen function, 290-292 
handling routines, 21 
header. See Header files 
include, naming conventions, x 
increasing system limit, 42 
information about open, _fstat function, 326-328 
length, _filelength function, 280—281 
locking bytes in, _locking function, 460-462 
low-level I/O, reading and writing data, 39 
object. See Object (.OBJ) files 
opening 
described, 39 
_dos_open function, 212-213 
fopen function, 290-292 
for file sharing, _sopen function, 714-716 
_open function, 553-556 
pointers. See File pointers 
reading data from 
_dos_open function, 214-215 
_read function, 611-612 
renaming, rename function, 625-626 
searching for files using environment paths, 
_searchenv function, 643-644 
setting 
attributes, dos_setfileattr function, 222—223 
modification time, _utime function, 834-835 
permission masks, _umask function, 825-826 


Files (continued) 
setting (continued) 
time, date, dos_setftime function, 224—226 
translation mode, _setmode function, 670—671 
startup, modified, 42 
status information about, _ stat function, 734—735 
temporary 
creating, tmpfile function, 815-816 
removing, _rmtmp function, 631-632 
testing for end-of-file, _eof function, 244—245 
writing 
buffers to, _dos_write function, 232—233 
data to, _write function, 887-888 
Fill masks 
getting current, _ getfillmask function, 362—363 
setting, _setfillmask function, 660-661 
Filling display area with color, _floodfill and 
_floodfill_w functions, 283-284 
Finding 
characters 
in buffers, memchr and _fmemchr functions, 
498-499 
in strings, strchr and _ fstrchr functions, 740-742 
files with specified attributes, _dos_find functions, 
191-193 
first substring, strspn and _fstrspn functions, 
784-785 
fonts, _setfont function, 662-664 
largest memory block size, _memmax function, 
508-509 
next token in string, strtok and _fstrtok functions, 
794-796 
substrings 
strcspn and _fstrcspn functions, 749-750 
Strstr and _ fstrstr functions, 786—787 
Floating point 
arguments, calculating absolute value, fabs and 
_fabsl functions, 258—259 
control word, getting and setting, _control87 
function, 160—162 
numbers 
converting between IEEE and Microsoft binary 
formats, fieeetomsbin and _fmsbintoieee 
functions, 279 
converting to strings, _fcvt function, 262—263 
getting mantissa and exponent, frexp and _frexpl 
functions, 314-315 
packages, resetting, _fpreset function, 295-298 
remainders, calculating, fmod and _fmod] 
functions, 288-289 
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Floating point (continued) 
Status word 
getting and clearing, _clear87 function, 148-149 
getting, _status87 function, 736—737 
support, 14—15 
values 
converting to strings, _gcvt function, 340-341 
splitting into mantissa and exponent, modf and 
_modfl functions, 523-524 
_floodfill function, 283-284 
_floodfill_w function, 283-284 
floor function, 285—286 
_floorl function, 285—286 
_flushall function, 287 
Flushing 
files to disks 
_commit function, 158—159 
COMMODE.OBJ, 33, 37 
_dos_commit function, 187-188 
_fdopen function, 264-292 
fopen function, 290—292 
streams 
_flushall function, 287 
fflush function, 271—272 
_fmalloc function, 479-482 
_fmblen function, 487-488 
_fmbstowcs function, 489-490 
_fmbtowc function, 491-493 
_fmemccpy function, 496-497 
_fmemchr function, 498-499 
_fmemcmp function, 500—502 
_fmemcpy function, 503-505 
_fmemicmp function, 506—507 
_fmemmove function, 510-512 
_fmemset function, 513-514 
fmod function, 288—289 
_fmode variable, 64 
_fmod1 function, 288—289 
_fmsbintoieee function, 279 
_fonexit function, 531-532 
Fonts 
displaying, 28-29 
finding single, _setfont function, 662-664 
freeing memory used by, _unregisterfonts function, 
833 
getting characteristics, _getfontinfo function, 364 
getting width in pixels, _getgtextextent function, 
365 
initializing fonts graphics system, _registerfonts 
function, 618 
library, xii 
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fopen function, 290—292 
_FP_OFF function, 293—294 
_FP_SEG function, 293-294 
_fpreset function, 295-298 
fprintf function, 299-300 
fputc function, 301-302 
_fputchar function, 301-302 
fputs function, 303 

fread function, 304—305 
_frealloc function, 613-615 
free functions, 306—308 
_freect function, 309-310 
freopen function, 311-313 
frexp function, 314-315 
_frexpl function, 314—315 
fscanf function, 316—317 
fseek function, 318—320 
fsetpos function, 321-322 
_fsopen function, 323-325 
_fstat function, 326-328 
_fstrcat function, 738—739 
_fstrchr function, 740—742 
_fstremp function, 743-745 
_fstrepy function, 747-748 
_fstrespn function, 749-750 
_fstrdup function, 753-754 
_fstricmp function, 759-760 
_fstrlen function, 761—762 
_fstrlwr function, 763—764 
_fstrncat function, 765-766 
_fstrncmp function, 767—769 
_fstrncpy function, 770-771 
_fstrnicmp function, 772—773 
_fstrnset function, 774—775 
_fstrpbrk function, 776-777 
_fstrrchr function, 778—779 
_fstrset function, 782—783 
_fstrspn function, 784—785 
_fstrstr function, 786-787 
_fstrtok function, 794—796 
_fstrupr function, 797-798 
ftell function, 329-330 
_ftime function, 33 1—332 
_fullpath function, 333-334 


Function declarations in header files, 7—8 


Functions 
See also Routines 
Bessel, 103-105 
~ BIOS interface (list), 55 


buffer-manipulation (list), 18 
character classification and conversion (list), 19 


Functions (continued) 


console and port I/O (lst), 43 
data-conversion (list), 20 
defined, 9 
difference from macros, 9-11 
directory control (list), 20 
DOS interface (list), 56-57 
file-handling 
(list), 21 
using, 21 
graphics 
analyzing presentation (list), 30 
configuring mode and environment (list), 22—23 
creating output (list), 26—27 
creating text output (list), 27 
displaying fonts (list), 28-29 
displaying presentation (list), 29-30 
low-level palette (list), 25 
low-level, character-font (list), 22 
presentation (list), 29 
presentation, manipulating structures (list), 30-31 
setting attributes (list), 25 
setting coordinates (list), 23-24 
transferring images (list), 28 
1/O 
(list), 33-35 
predefined stream pointers (list), 36 
internationalization (list), 44 
low-level I/O (list), 38-39 
math 
described, 44, 46 
(list), 45-46 
memory allocation (list), 46-47 
process and environment (list), 50-51 
Quick Win (list), 53 
requiring floating-point support (list), 14 
_sSpawn and _exec forms (list), 52 
stack checking (list), 12 
string manipulation (list), 54—55 
time 
current (list), 58-59 
variables (list), 62 
using huge arrays with, 16 
variable-length arguments list (list), 59 


_fwestombs function, 867—868 
_fwctomb function, 869~—870 
_fwopen function, 335-337 
fwrite function, 338-339 


G 


_gcvt function, 340-341 
Generating pseudorandom number, rand function, 
609-610 

_getactivepage function, 342-343 
_getarcinfo function, 344 
_getbkcolor function, 345 
getc function, 346-347 
_getch function, 348-349 
getchar function, 346-347 
_getche function, 348-349 
_getcolor function, 350-351 
_getcurrentposition functions, 352-353 
_getcwd function, 354-355 
_getdcwd function, 356-358 
_getdrive function, 359 
getenv function, 360-361 
_getfillmask function, 362-363 
_getfontinfo function, 364 
_getgtextextent function, 365 
_getgtextvector function, 366 
_getimage function, 367-369 
_getimage_w function, 367-369 
_getimage_wxy function, 367-369 
_getlinestyle function, 370-371 
_getpid function, 373 
_getpixel function, 374-375 
_getpixel_w function, 374-375 
gets function, 376-377 
_gettextcolor function, 378 
_gettextcursor function, 379 
_gettextposition function, 380-381 
_gettextwindow function, 382 
_getvideoconfig function, 383-385 
_getviewcoord function, 386-387 
_getviewcoord_w function, 386-387 
_getviewcoord_wxy function, 386-387 
_getvisualpage function, 388 
_getw function, 389-390 
_getwindowcoord function, 391 
_getwritemode function, 392-393 
Global variables 

_amblksize, 61-62 

_cpumode, 65 

daytime, 62 

_doserrno, 63—64 

environment, 66 

ermo, 63-64 

error codes, 63-64 

_fmode, 64 
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Global variables (continued) 


locale macros, 65 
_osmajor, 65 
_osminor, 65 
_osmode, 65 
_osversion, 65 
_pgmptr, 67 
_psp, 66-67 
sys_errlist, 63-64 
sys_nerr, 63-64 
timezone, 62 
tzname, 62 

using, 61 

version of current operating system, 14 


gmtime function, 394—395 
Graphics 


character-font, using, 22 
displaying fonts, 28—29 
environment, configuring routines, 22 
error handling, 13 
function call status, returning most recent, _ grstatus 
function, 396-399 
getting 
current fill masks, _ getfillmask function, 
362-363 
Output position, _getcurrentposition 
functions, 352-353 
video configuration information, 
_getvideoconfig function, 383-385 
image-transfer functions, 28 
images 
getting memory to store, _imagesize functions, 
426-427 
storing in buffers, _getimage functions, 367—369 
library, expanded, xiii 
low-level 
palette routines, 25 
using, 22 
mode, configuring routines, 22 
moving current positions, _moveto functions, 
527-528 
output functions, 26—27 
presentation 
analyzing charts, 30 
functions, 29, 31 
initializing, _pg_initchart function, 570 
manipulating structures, 30-31 
redefining viewports, _setviewport function, 
699-700 | 
routines, 22—31 
selecting palettes, _selectpalette function, 647-649 
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Graphics (continued) 
setting 
attributes, 25—26 
clipping region, _setcliprgn function, 656-657 
colors, 25 
coordinates, 23—24 
cursor toggle, _displaycursor function, 179-180 
text output routines, 27-28 
_grstatus function, 396-399 


H 


_halloc function, 400-401 
Handling errors. See Error handling 
_hard functions, 402-405 
_harderr function, 402—405 
_hardresume function, 402—405 
_hardretn function, 402—405 
Header files 
contents, use, 5 
function declarations, 7-8 
including necessary definitions, 6 
using, 6-8 
_heapadd function, 406-409 
_heapchk function, 410-412 
_heapmin function, 413-414 
Heaps 
advantages of using based, 49 
allocating, _bheapseg function, 107—109 
checking, _heapset functions, 415-417 
consistency checks, _heapchk functions, 410-412 
far 
defined, 48 
routines, 48 
freeing, _bfreeseg function, 106 
debugging 
_heapchk functions, 410-412 
_heapset functions, 415-417 
_heapwalk functions, 418-421 
memory granularity variable, 61 
minimizing, _heapmin functions, 413-414 
near 
defined, 48 
routines, 48 
_heapset function, 415-417 
_heapwalk function, 418-421 
_hfree function, 422-423 
_hypot function, 424—425 
Hypotenuses, calculating, hypot and _hypotl 
functions, 424—425 
_hypotl function, 424-425 


I/O functions 
based heaps, 49 
buffering, 33 
closing files, 40 
committing buffer contents to disk, 37 
console, 43—44 
increasing system limits, 42 
low-level routines, 38-39 
near and far heaps, 48—49 
opening files, 39 
port, 43-44 
reading and writing data, 39 
reading and writing operations, 37-38 
searching and sorting routines (list), 54 
stream buffering, 36 
system calls, 55 
text and binary modes, 32 
types, 31 
using modified startup files, 42 
variable-length argument lists, 59 
virtual memory allocation, 60 
Identification, getting process, _getpid function, 
373 


JEEE binary format, converting floating-point 


numbers to Microsoft binary formats, 
_fieeetomsbin and _fmsbintoieee functions, 
279 
Images 
graphics. See Graphics 
retrieving from buffers, _putimage functions, 
600-60 1 
storing in buffers, _getimage functions, 367—369 
_imagesize function, 426-427 


_imagesize_w function, 426—427 


_imagesize_wxy function, 426—427 
Include files, naming conventions, x 
Initializing 
characters of strings to given characters, _strnset 
and _fstrnset functions, 774-775 
chart environment, _pg_defaultchart function, 
562-563 
fonts graphics system, _registerfonts function, 618 
presentation graphics, _pg_initchart function, 570 
virtual memory manager, _ vheapinit function, 
845-846 
_inp function, 428 
Inputting bytes or words from port, _inp and _inpw 
functions, 428 
_inpw function, 428 


Installing terminate-and-stay-resident programs, 
_dos_keep function, 210-211 
_int86 function, 429-430 
_int86x function, 431-432 
_intdos function, 433-434 
_intdosx function, 435-436 
Integers 
calculating absolute value of long integers, labs 
function, 445-446 
converting 
long integers to strings, _ltoa function, 474-475 
to strings, _itoa function, 442-443 
unsigned long integers to strings, _ultoa function, 
823-824 
getting from stream, _getw function, 389-390 
testing values, is functions, 437-440 
writing to streams, _putw function, 603-604 
Internationalization routines, 44 
Interrupt vectors, setting, _dos_setvect function, 
229-231 
Interrupts 
8086 
executing and accepting segment-register values, 
_int86x function, 431—432 
executing, _1nt86 function, 429-430 
chaining between handlers, _chain_intr function, 
138-139 
disabling, _ disable function, 178 
enabling, enable function, 243 
getting vector values, _dos_getvect function, 209 
setting signal handling, signal function, 707-711 
is functions, 437-440 
isalnum function, 437—440 
isalpha function, 437-440 
__isascii function, 437-440 
_isatty function, 441 
iscntrl function, 437-440 
__iscsym function, 437—440 
__iscsymf function, 437—440 
Italics, use of, xiv 
_itoa function, 442-443 


J 


_jO function, 103-105 
_jOl function, 103—105 
_jl function, 103-105 
_jll function, 103-105 
_jn function, 103-105 
_jnl function, 103—105 
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K 


_kbhit function, 444 
Keyboard, checking console for input, _kbhit 
function, 444 


L 


labs function, 445-446 
Idexp function, 447-448 
_Idexpl function, 447-448 
Idiv function, 449-450 
Idiv_t function, 449-450 
_lIfind function, 451-452 
Libraries 
linking, 6 
procedures generally, 5-16 
routines, calling, 5—6 
Library files, use, 5 
Library routines 
calling, 5-6 
file and path names, 8—9 
Line drawing 
getting mode, _getwritemode function, 392—393 
setting logical mode for, _setwritemode function, 
706 
to points, _lineto functions, 453-454 
Lines 
drawing. See Line drawing 
getting from streams, gets function, 376-377 
getting style, _getlinestyle function, 370-371 
setting style, _setlinestyle function, 667 
_lineto function, 453-454 
_lineto_w function, 453-454 
Linking libraries, 6 
Loading 
child process and executing, _exec functions, 
246-250 
virtual memory block into DOS memory 
and locking, _vlock function, 851-853 
virtual memory blocks into DOS memory 
_vload function, 848—850 
localeconv function, 455—457 


Locales 
defining, setlocale function, 668-669 
macros, 65 


settings, getting information on, localeconv 
function, 455—457 
localtime function, 458—459 
Locking bytes in file, _locking function, 460—462 
_locking function, 460-462 
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Locks, returning number held on virtual memory 
block, _vlockcnt function, 854—856 

log functions, 463-464 

logl10 function, 463-464 

_logl01 function, 463-464 

Logarithms, calculating, log functions, 445-446, 
463-464 

_logl function, 463-464 

long double functions, 465 

longjmp function, 466-467 

_lrotl function, 468 

_lrotr function, 468 

_lsearch function, 469—470 

_lseek function, 471-473 

_ltoa function, 474—475 


Macros 
benefits over functions, 9-11 
defined, 9 
locale, 65 
_makepath function, 476-478 
malloc functions, 479-482 
Masks, file-permission-setting, _umask function, 
825-826 
Math 
error handling, _matherr and _matherrl functions, 
483-485 
routines, 44, 46 
_matherr function, 483-485 
_matherrl function, 483-485 
__max function, 486 
Maximum, returning larger of two values, __ max 
function, 486 
MB_CUR_MAX constant, 65 
MB_LEN_MAX constant, 65 
mblen function, 487-488 
mbstowcs function, 489-490 
mbtowc function, 491-493 
_memavl function, 494—495 
_memcecpy function, 496-497 
memchr function, 498—499 
memcmp function, 500-502 
memcpy function, 503-505 
_memicmp function, 506-507 
_memmax function, 508—509 
memmove function, 510-512 


Memory 


adding to heaps, _heapadd functions, 406—409 
arrays 
allocating, calloc functions, 131-132 
using huge, 16 
blocks 
allocating, _dos_allocmem function, 183-184 
allocating, _halloc function, 400-401 
changing size, _expand functions, 255—257 
deallocating, free functions, 306—308 
deallocating virtual, _vfree function, 844 
finding size of largest, _memmax function, 


508-509 

loading into DOS memory, _vload function, 
848-850 | 

returning size allocated in heap, _msize function, 
529-530 


virtual, allocating, _vmalloc function, 857-858 
virtual, loading into DOS memory and locking, 
_vlock function, 851-853 
virtual, returning number of locks on, _ vlockcnt 
function, 854-856 
virtual, returning size of, _vmsize function, 859 
virtual, unlocking, _vunlock function, 862 
changing segment size, _dos_setblock function, 
216-217 | 
freeing from fonts, _unregisterfonts function, 833 
freeing, _hfree function, 422-423 
getting to store images, _imagesize functions, 
426-427 
heaps, minimizing, _heapmin functions, 413-414 
manager. See Memory manager 
releasing, _dos_freemem function, 194-195 
returning amount available for allocation, _freect 
function, 309-310 
returning available, _memavl function, 494—495 
stacks, getting available, _stackavail function, 733 


Memory allocation 


See also Memory 
controlling heap granularity, _amblksize variable, 
61 
deallocating 
blocks, free functions, 306—308 
virtual memory blocks, _vfree function, 844 
freeing memory 
from fonts, _unregisterfonts function, 833 
from heaps, _bfreeseg function, 106 
huge array functions (list), 16 
malloc functions, 479-482 
_memmax function, 508-509 
_msize functions, 529—530 


Memory allocation (continued) 
releasing memory, _dos_freemem function, 
194-195 
returning amount available for, _freect function, 
309-3 10 
routines, 46, 48 
stacks 
_alloca function, 84—85 
_stackavail function, 733 
virtual 
blocks, number of times locked, _vlock function, 
851-853 
blocks, _vmalloc function, 857—858 
functions (list), 60 
Memory manager 
initializing virtual, _vheapinit function, 845-846 
terminating virtual, _vheapterm function, 847 
memset function, 513—514 
__ min function, 515 
Minimizing heaps, _heapmin functions, 413-414 
Minimum, returning smallest of two values, __ min 
function, 515 
_mkdir function, 516—517 
_mktemp function, 21, 518-520 
mktime function, 521-522 
modf function, 523-524 
_modfl function, 523-524 
_movedate function, 525—526 
_moveto function, 527-528 
_moveto_w function, 527-528 


Moving 
buffers, memmove and _fmemmove functions, 
510-512 
characters to another segment, _movedate function, 
525-526 


file pointers, _Iseek function, 471-473 
graphics position, _moveto functions, 527-528 
view-coordinate origins, _setvieworg function, 
697-698 
_msize function, 529-530 


_ncalloc function, 131-132 
_nexpand function, 255-257 
_nfrealloc function, 613-615 
_nfree function, 306—308 
_nheapchk function, 410-412 
_nheapmin function, 413-414 
_nheapset function, 415-417 
_nheapwalk function, 418-421 
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_nmalloc function, 479-482 
_nstrdup function, 753-754 
Numbers 
converting double to strings, _ecvt function, 
239-240 
pseudorandom, generating, rand function, 609-610 
real, computing from mantissa and exponent, Idexp 
and _Idexpl functions, 447-448 


0 


Object (.OBJ) files, linking with library files, 6 
_onexit function, 53 1—532 
_open function, 533-536 
Opening 
file streams for Quick Win windows, _fwopen 
function, 335-337 
files 
_dos_open function, 212-213 
fopen function, 290-292 
for file sharing, _sopen function, 714—716 
_open function, 533-536 
QuickWin windows, _wopen function, 882-884 
streams with file sharing, _fsopen function, 
323-325 * 
Operating systems 
case sensitivity, 9 
file and path names, 8—9 
general considerations, 13-14 
specifying versions, 65 
variable mode, 65 
_osmajor variable, 65 
_osminor variable, 65 
_osmode variable, 65 
_osversion variable, 65 
_outgtext function, 537-539 
_outmem function, 540-541 
_outp function, 542-544 
Outputting bytes at port, _outp and _outpw 
functions, 542—544 
_outpw function, 542-544 
_outtext function, 545-546 


p 


Page numbers 
active, setting _setactivepage function, 650-651 
current active, getting _getactivepage function, 
342-343 
current visual, getting, _getvisualpage function, 388 
Pages, visual, setting, _setvisualpage function, 701 


SS 
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Palettes 
getting colors, lines, styles, patterns, pg getpalette 
function, 565-567 
remapping colors, _remapallpalette and 
_remappalette functions, 619-623 
resetting to default, pg resetpalette function, 571 
selecting graphics, _selectpalette function, 647-649 
setting values, _pg_setpalette function, 574 
Parameters. See Arguments 
Parent process defined, 51 
Path names 
breaking into components, _splitpath function, 
723-724 
creating, makepath function, 476—478 
delimiters, 9 
getting current directory, _getdcwd function, 
356-358 
making absolute from relative names, _fullpath 
function, 333-334 
operating system conventions, 8-9 
perror function, 547-548 
_pg_analyzechartms function, 549-551 
_pg_analyzechart function, 549-551 
_pg_analyzepie function, 552 
_pg_analyzescatter function, 553-554 
_pg_analyzescatterms function, 553-554 
_pg_chart function, 555-557 
_pg_chartms function, 555-557 
_pg_chartpie function, 558-559 
_pg_chartscatter function, 560-561 
_pg_chartscatterms function, 560-561 
_pg_defaultchart function, 562-563 
_pg_getchardef function, 564 
_pg_getpalette function, 565-567 
_pg_getstyleset function, 568 
_pg_hlabelchart function, 569 
_pg_initchart function, 570 
_pg_resetpalette function, 571 
_pg_resetstyleset function, 572 
_pg_setchardef function, 573 
_pg_setpalette function, 574 
_pg_setstyleset function, 575 
_pg_vlabelchart function, 576 
_pgmptr variable, 67 
Pie charts 
analyzing data series for, _pg_ analyzepie function, 
552 
displaying, _pg_chartpie function, 558-559 
_pie function, 577-579 
Pies, determining viewpoint coordinate endpoints, 
_getarcinfo function, 344 


_pie_w function, 577-579 
_pie_wxy function, 577-579 
Pixels 
converting coordinates, 23 
getting values, _getpixel functions, 374-375 
setting to current color, _setpixel functions, 
676-677 
Pointers 
far, setting offsets and segments, _KP_OFF and 
_FP_SEG functions, 293-294 
file. See File pointers 
_polygon functions, 580-582 
Polygons, drawing, _polygon functions, 580-582 
_polygon_w function, 580-582 
_polygon_wxy function, 580-582 
Ports, I/O routines, 43—44 
Position, getting current and returning as structure, 
_getcurrentposition functions, 352-353 
pow functions, 583-584 
Powers, calculating, pow functions, 583-584 
Presentation graphics 
displaying, 29-30 
functions, x1i, 29-31 
initializing, pg initchart function, 570 
printf function, 585-592 
Printing 
data to stream, fprintf function, 299-300 
error information, 63 
error messages 
perror function, 547-548 
strerror and _ strerror functions, 755—756 
font-based text in graphics mode, _ outgtext 
function, 537-539 
output to streams, printf function, 585-592 
text 
graphics mode, _outtext function, 545-546 
of specified length in graphics mode, _outmem 
function, 540-541 
to console, _cprintf function, 165-166 
Process control functions, 49-52 
Processes 
child, loading and executing, _exec functions, 
246-250 
identification, _getpid function, 373 
terminating calling, exit and _exit functions, 
251-252 
Processing at exit, atexit and _fatexit functions, 
96-97 


Programs 
aborting, assert function, 92-93 
executing, sending signal to, raise function, 
607-608 
saving current state, setjmp function, 666 
_psp variable, 66—67 
purchar function, 593-594 
putc function, 593-594 
_putch function, 595-596 
_putenv function, 597-599 
_putimage function, 600-601 
_putimage_w function, 600-601 
puts function, 602 
Putting strings to the console, _cputs function, 167 
_putw function, 603-604 


Q 


qsort function, 605—606 
Quick Win 
closing window’s file handle, _wclose function, 
865-866 
functions, x1, 53 
menu items, choosing, _wmenuclick function, 
880-88 1 
program exit behavior, _wgetexit function, 871-872 
setting strings for About dialog boxes, _wabout 
function, 863-864 
specifying exit behavior of application, _wsetexit 
function, 889-89] 
windows 
activating, _wsetfocus function, 892-893 
getting current screen-buffer size, _wgetscreenbuf 
function, 875-876 
getting current size, position, _wgetsize function, 
877-879 
getting file handles, _wgetfocus function, 873-874 
opening, _wopen function, 882—884 
setting screen buffer size, _wsetscreenbuf function, 
894-895 
setting size, screen position, _wsetsize function, 
896-897 
yielding processor control for Windows queue 
servicing, 898-899 
Quotation marks, use of, xv 
Quotients, computing, Idiv and Idiv_t functions, 
449-450 


R 


raise function, 607—608 
rand function, 609-610 
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Random 
number generation, rand function, 609-610 
Starting point, setting, srand function, 729-730 
_read function, 611-612 
Reading 
characters from streams, getc and getchar 
functions, 346—347 
console data, _cscanf function, 171-172 
file data 
_dos_open function, 214—215 
_read function, 611-612 
formatted data 
from input stream, scanf function, 635-639 
from strings, sscanf function, 73 1—732 
stream data 
fread function, 304—305 
fscanf function, 316-317 
realloc functions, 613-615 
Reallocating memory blocks, realloc functions, 
613-615 
_rectangle function, 616-617 
Rectangles, drawing, _rectangle functions, 616-617 
_rectangle_w function, 616-617 
_rectangle_wxy function, 616-617 
Register values, getting, _dosexterr function, 
234-235 
_registerfonts function, 618 
Registering routine to be called on exit, 
_fonexit and _onexit functions, 531-532 
Releasing memory block, _dos_freemem function, 
194-195 
_remapallpalette function, 619-623 
_remappalette function, 619-623 
Remapping palette colors, _remapallpalette and 
_remappalette functions, 619-623 
remove function, 624 
Removing 
directories, rmdir function, 629-630 
files 
remove function, 624 
temporary, _rmtmp function, 631-632 
rename function, 625-626 
Renaming 
directories, rename function, 625-626 
files, rename function, 625—626 
Repositioning file pointers, rewind function, 
627-628 
Resetting 
floating-point packages, _fpreset function, 295—298 
palette values, _pg_resetpalette function, 571 
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Resetting (continued) 
stream error indicator, clearerr function, 150—151 
styleset to default, pg resetstyleset function, 572 
Restoring stack environment and execution locale, 
longjmp function, 466-467 
Reversing characters in strings, _strrev and 
_fstrrev functions, 780-781 
rewind function, 627-628 
_rmdir function, 629-630 
_rmtmp function, 631-632 
Rotating bits 
_lrotl and _lrotr functions, 468 
_rotl and _rotr functions, 633-634 
_rotl function, 633-634 
_rotr function, 633-634 
Routines 
choosing functions or macros, 9—11 
described by category, 17-60 
registering to be called on exit, _fonexit and 
_onexit functions, 531—532 


S 


Saving current state of program, setymp function, 
666 | 
scanf function, 635-639 
Scanning strings 
for characters in specified character sets, strpbrk 
| and _fstrpbrk functions, 776-777 
for last occurrence of characters, strrchr and 
_fstrrchr functions, 778—779 
Scatter charts 
analyzing data series, pg _analyzescatter functions, 
553-554 
displaying, _pg_chartscatter functions, 560-561 
Screen area, clearing, _clearscreen function, 
152-153 
Scrolling text in text window, _scrolltextwindow 
function, 640-642 
_scrolltextwindow function, 640-642 
_searchenv function, 643-644 
Searching 
and sorting routines (list), 54 
arrays 
for keys, _Ifind function, 451-452 
for values, _lsearch function, 469-470 
with binary search, bsearch function, 127-128 
for files using environment paths, _searchenv 
function, 643-644 
Segment registers, getting current values, _segread 
function, 645-646 


_segread function, 645-646 
_selectpalette function, 647-649 
Sending signal to executing programs, 
raise function, 607-608 
_set_new_handler function, 672—675 
_setactivepage function, 650-651 
setbkcolor function, 652-653 
_set_bnew_handler function, 672-675 
setbuf function, 654-655 
_setcliprgn function, 656—657 
_setcolor function, 658-659 
_setfillmask function, 660-661 
_set_fnew_handler function, 672—675 
_setfont function, 662—664 
_setgtextvector function, 665 
setjmp function, 666 
_Setlinestyle function, 667 
setlocale function, 668-669 
_setmode function, 670-671 
_set_nnew_handler function, 672—675 
_setpixel function, 676-677 
_setpixel_w function, 676-677 
_settextcolor function, 678—680 
_settextcursor function, 681-682 
_settextposition function, 683-684 
_settextrows function, 685-686 
_settextwindow function, 687 
Setting 
active page, _setactivepage function, 650-651 
attributes of files, directories, dos_setfileattr 
function, 222—223 
buffers to specified character, memset and 
_fmemset functions, 513-514 
characters of strings to character, _ strset and 
_fstrset functions, 782—783 
clipping region for graphics, _setcliprgn function, 
656-657 
colors 
background, _setbkcolor function, 652-653 
current, _setcolor function, 658-659 
text, _settextcolor function, 678-680 
cursor 
attributes, _settextcursor function, 681-682 
toggle for graphics, _displaycursor function, 
179-180 
date and time for files, _dos_setftime function, 
224-226 
default drive, _dos_setdrive function, 220-221 
far-pointer offsets and segments, _FP_OFF and 
_FP_SEG functions, 293-294 


Setting (continued) 
file default permission mask, _umask function, 
825-826 
file translation mode, _setmode function, 670—67 1 
fill masks, _ setfillmask function, 660—661 
floating point control word, _control87 function, 
160-162 
interrupt 
signal handling, signal function, 707-711 
vector, dos_setvect function, 229-231 
line drawing logical mode, _setwritemode function, 
706 
line styles, _setlinestyle function, 667 
locales, setlocale function, 668-669 
palette values, _pg_setpalette function, 574 
pixel bitmaps for specified characters, 
_pg_setchardef function, 573 
pixels to current color, _setpixel functions, 676-677 
screen rows for text, _settextrows function, 
685-686 
stream position indicators, fsetpos function, 
321—322 
styleset, pg_setstyleset function, 575 
system 
date, dos_setdate function, 218-219 
time, _dos_settime function, 227—228 
text position, _settextposition function, 683-684 
video mode, _setvideomode function, 690-694 
video modes and rows in text modes, 
_setvideomoderows function, 695-696 
visual pages, _setvisualpage function, 701 
_setvbuf function, 688-689 
_setvideomode function, 690-694 
_setvideomoderows function, 695-696 
_setvieworg function, 697-698 
_setviewport function, 699-700 
_setvisualpage function, 701 
_setwritemode function, 706 
signal function, 50, 707-711 
Signaling executing programs, raise function, 
607-608 
Sines, calculating, sin functions, 712-713 
_snprintf function, 725-726 
_sopen function, 714-716 
Sorting, gsort function, 605—606 
_Spawn functions, 717-722 
_spawnl function, 717-722 
_spawnile function, 717—722 
_Spawnlp function, 717—722 
_spawnlpe function, 717-722 
_Spawnv function, 717-722 
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_spawnve function, 717-722 
_spawnvp function, 717-722 
_spawnvpe function, 717-722 
_splitpath function, 723-724 
Splitting floating point values into mantissa and 
exponent, modf and _modfl functions, 
523-524 
sprintf function, 725-726 
sqrt function, 727-728 
_sqrtl function, 727-728 
Square roots, calculating, sqrt and _sqrtl functions, 
727-728 
srand function, 729-730 
sscanf function, 731—732 
_stackavail function, 733 
Stacks 
allocating memory on, _alloca function, 84-85 
checking on entry, 11-12 
getting available size, _stackavail function, 733 
restoring environment, longymp function, 466-467 
Standard types 
(list), 67-69 
using, 61, 69 
Starting point, setting random, srand function, 
729-730 
Startup, modifying CSTARTUP.BAT, 42 
_ stat function, 734-735 
Status information 
getting on files, _stat function, 734—735 
returning graphics function call, _grstatus function, 
396-399 
_status87 function, 736—737 
Storing images in buffers, _getimage functions, 
367-369 
streat function, 738-739 
strchr function, 740-742 
strcmp function, 743-745 
_strcmpi function, 743-745, 759-760 
strcoll function, 746 
strcpy function, 747—748 
strespn function, 749-750 
_strdate function, 751—752 
_strdup functions, 753-754 
Stream I/O 
buffering, 36 
controlling, setbuf function, 654—655 
error handling, 13 
error testing, 38 
predefined pointers, 35-36 
routines, 33-35 
transferring data, 37-38 
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Stream pointers 


defined, 33 
predefined, 35-36 


Streams 


associating with files, _fdopen function, 264-266 
buffer control 

setbuf function, 654—655 

setvbuf function, 688—689 
closing 

fclose and _ fcloseall functions, 260-261 

functions, 37 
end-of-file testing, feof function, 267—268 
flushing 

_flushall function, 287 

fflush function, 271—272 
getting 

file handles, _fileno function, 282 

file-position indicator, fgetpos function, 275-276 

integers, _getw function, 389-390 

lines from, gets function, 376-377 

strings from, fgets function, 277-278 
increasing maximum number, 40-42 
opening 

functions, 35 

with file sharing, _fsopen function, 323-325 
pointers. See Stream pointers 
printing 

data to, fprintf function, 299-300 

formatted output to, printf function, 585-592 
pushing characters back onto, ungetc function, 

827-828 

reading characters from 

fgetc and _fgetchar functions, 273-274 

getc and getchar functions, 346-347 
reading data from 

fread function, 304—305 

fscanf function, 316-317 
resetting error indicator, clearerr function, 150-151 
setting position indicator, fsetpos function, 321—322 
testing for errors, ferror function, 269-270 
writing 

characters to, fputc and _fputchar functions, 

301-302 


characters to, putc and putchar functions, 593-594 


data from, fwrite function, 338—339 
integers to, _putw function, 603-604 
strings to, fputs function, 303 


strerror function, 755—756 


String manipulation routines, 54—55 
Strings 


appending 
characters of, strncat and _fstrncat functions, 
765-766 
strcat and _ fstrcat functions, 738—739 
comparing 
characters from two, strncmp and _fstrncmp 
functions, 767—769 


characters of two strings, _strnicmp and _fstrnicmp 


functions, 772-773 
lowercase, _stricmp and _fstricmp functions, 
759-760 
stremp and _fstremp functions, 743-745 
strcoll function, 746 
converting 
double numbers to, _ecvt function, 239—240 
long integers to, _ltoa function, 474-475 
to lowercase, _strlwr and _fstrlwr functions, 
763-764 
to uppercase, _strupr and _fstrupr functions, 
797-798 
converting to values 
double, atof function, 98—100 
integer, _atold function, 98-100 
long double, atoi function, 98—100 
long, atol function, 98-100 
copying, strepy and _fstrcpy functions, 747-748 
duplicating, _strdup functions, 753-754 
finding 


characters in, strchr and _fstrchr functions, 740—742 


next token in, strtok and _fstrtok functions, 
794-796 
substrings first, strspn and _fstrspn functions, 
784-785 
substrings in, strcspn and _fstrcspn functions, 
749-750 
substrings, strstr and _fstrstr functions, 786-787 
getting 
character strings from console, _cgets function, 
136-137 
from streams, fgets function, 277—278 
length, strlen and _fstrlen functions, 761—762 
putting to console, _cputs function, 167 
reading formatted data from, sscanf function, 
731-732 
time, formatting, strftime function, 757—758 
transforming based on locale-specific information, 


_strerror function, 755—756 
strftime function, 757—758 
_stricmp function, 743-745, 759-760 


strxfrm function, 799-800 


Strings (continued) 
writing 
formatted data to, sprintf function, 725—726 
to output, puts function, 602 
to streams, fputs function, 303 
strlen function, 761—762 
_strlwr function, 763-764 
strncat function, 765—766 
strncmp function, 767—769 
strncpy function, 770-771 
_strnicmp function, 772—773 
_strnset function, 774-775 
strpbrk function, 776-777 
strrchr function, 778-779 
_strset function, 782—783 
strspn function, 784-785 
strstr function, 786—787 
_strtime function, 788—789 
strtod function, 790—793 
strtok function, 794—796 
strtol function, 790-793 
_strtold function, 790-793 
strtoul function, 790-793 
_strupr function, 797-798 
strxfrm function, 799—800 
Styleset 
getting current array, _pg_getstyleset function, 568 
resetting to default, _pg_resetstyleset function, 572 
setting current, pg_setstyleset function, 575 
_swab function, 801—802 
Swapping bytes, _swab function, 801—802 
sys_errlist variable, 63-64 
sys_nerr variable, 63-64 
System call routines, 55 
System date, getting, dos_getdate function, 
196-197 
system function, 803-804 
System time, getting 
_dos_gettime function, 207—208 
time function, 812—814 


T 


tan functions, 805—806 

Tangents, calculating, tan functions, 805-806 
tanh function, 805—806 

_tanhl function, 805—806 

_tanl function, 805—806 

_tell function, 807-808 

_tempnam function, 809-811 
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Terminate-and-stay-resident programs, installing, 
_dos_keep function, 210-211 
Terminating 
atexit function, 96—97 
calling processes, exit and _exit functions, 251-252 
virtual memory manager, _vheapterm function, 847 
Testing 
end-of-file 
_eof function, 244—245 
on given stream, 13 
on streams, feof function, 267—268 
streams for errors, ferror function, 269—270 
Text 
changing orientation 
of font text output, _ getgtextvector function, 366 
of output, _setgtextvector function, 665 
colors, setting, _settextcolor function, 678—680 
creating output, 27-28 
current cursor attribute in text video mode, 
_gettextcursor function, 379 
current position, _gettextposition function, 380-381 
font-based, getting width in pixels, _getgtextextent 
function, 365 
modes, setting number of rows, 
_setvideomoderows function, 695-696 
printing 
font-based in graphics mode, _outgtext function, 
537-539 
graphics mode, _outtext function, 545-546 
specified length in graphics mode, _outmem 
function, 540-541 
scrolling in text window, _scrolltextwindow 
function, 640-642 
setting 
position, _settextposition function, 683-684 
screen rows, _settextrows function, 685—686 
windows 
creating, _settextwindow function, 687 
getting boundaries, _gettextwindow function, 382 
writing 
horizontally on screen, _pg_hlabelchart function, 
569 
vertically on screen, _pg_vlabelchart function, 576 
32-bit targeting, DOS Extender described, x1 
Time 
calculating calling process, clock function, 154-155 
calling BIOS time and date services, 
_bios_timeofday function, 125-126 
converting 
local to calendar, mktime function, 521-522 
to character strings, ctime function, 173-174 
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Time (continued) 
converting (continued) 


values and correcting for zone, localtime function, 


458-459 
values to structures, gmtime function, 394-395 
copying to buffers, _ strtime function, 788-789 
current, getting, _ftime function, 331—332 
environment variables, setting, _tzset function, 
820-822 
finding difference between two times, difftime 
function, 176-177 
formatting strings, strftime function, 757—758 
functions 
described, 58-59 
(list), 58 
getting time file written, _dos_getftime function, 
204-206 
setting 
file modification, _utime function, 834—835 
for files, dos_setftime function, 224—226 
structures, converting to character strings, asctime 
function, 88-89 
system 
getting, dos_gettime function, 207—208 
getting, time function, 812-814 
setting, _dos_settime function, 227-228 
time function, 812—814 
timezone variable, 62 
tmpfile function, 815-816 
tmpnam function, 809-811 
__toascii function, 817-819 
Tokens, finding next in string, strtok and _fstrtok 
functions, 794-796 
tolower function, 817-819 
_toupper function, 817-819 
Transferring control to error handler, 
_set_new_handler functions, 672—675 
Transforming strings based on locale-specific 
information, strxfrm function, 799—800 
Triangles, calculating hypotenuse, _hypot and . 
_hypotl functions, 424—425 
TSR programs, installing, _dos_keep function, 
210-211 
Types, standard. See Standard types 
tzname variable, 62 
_tzset function, 820-822 


U 


_ultoa function, 823-824 
_umask function, 21, 825-826 


Underscore, document conventions, xiv 
ungetc function, 827-828 
_ungetch function, 829-830 
UNIX 
case sensitivity, 9 
compatibility, 1x 
naming conventions, 8 
path-name delimiters, 9 
programming, x1 
subdirectory conventions, 9 
_unlink function, 831—832 
Unlocking virtual memory blocks, _ vunlock 
function, 862 
_unregisterfonts function, 833 
Uppercase 
converting strings to, _strupr and _fstrupr 
functions, 797-798 
use of, Xiv 
_utime function, 834—835 


V 


va_arg function, 836-839 
va_end function, 836-839 
Values 
calculating 
ceilings, ceil and _ceill functions, 133-134 
floors, floor and _floorl functions, 285-286 
getting 
environment table, getenv function, 360-361 
register, _dosexterr function, 234—235 
returning 
maximum, __ max function, 486 
smallest of two, __ min function, 515 
searching for, _lsearch function, 469-470 
Variable-length argument lists, 59 
Variables, global. See Global variables 
va_Start function, 836-839 
vfprintf function, 840-843 
_vfree function, 844 
_vheapinit function, 845-846 
_vheapterm function, 847 
Video 
getting graphics configuration information, 
_getvideoconfig function, 383-385 
mode setting 
_setvideomode function, 690-694 
_setvideomoderows function, 695-696 


View coordinates 
moving origins, _setvieworg function, 697-698 
translating to window coordinates, 

_getwindowcoord function, 391 

translating to, _getviewcoord functions, 386-387 

Viewports, creating, _Ssetviewport function, 

699-700 

Virtual memory allocation functions (list), 60 

_vload function, 848—850 

_vlock function, 851—853 

_vlockent function, 854-856 

_vmalloc function, 857-858 

_vmsize function, 859 

vprintf function, 840-843 

_vrealloc function, 860-861 

_vsnprintf function, 840-843 

vsprintf function, 840-843 

_vunlock function, 862 


W 


_wabout function, 863-864 
_wclose function, 865—866 
wcstombs function, 867—868 
wctomb function, 869-870 
Wedges, drawing, _pie functions, 577-579 
_weetexit function, 871-872 
_weetfocus function, 873-874 
_wegetscreenbuf function, 875-876 
_wegetsize function, 877-879 
Windows 
compatibility, x1 
coordinates, translating view coordinates to, 
_getwindowcoord function, 391 
creating text, _settextwindow function, 687 
getting boundaries of current text windows, 
_gettextwindow function, 382 
programs, setting strings for About dialog boxes, 
_wabout function, 863-864 
Quick Win 
activating, _wsetfocus function, 892-893 
getting current screen buffer size, _wgetscreenbuf 
function, 875—876 
getting current size and position, _wgetsize 
function, 877—879 


opening file stream for, _fwopen function, 335-337 


opening, _wopen function, 882—884 

setting screen-buffer size, _wsetscreenbuf 
function, 894—895 

setting size, screen position, _wsetsize function, 
896-897 
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Windows (continued) 
scrolling text in, _scrolltextwindow function, 
640-642 
setting graphics, _setwindow function, 702—705 
_wmenuclick function, 880-88 1 
_wopen function, 882-884 
Word wrap, controlling, _wrapon function, 
885-886 
Words 
inputting from port, _inp and _inpw functions, 428 
outputting at port, outp and _outpw functions, 
542-544 
wrap controlling, _wrapon function, 885—886 
_wrapon function, 885-886 
_write function, 887-888 
Writing 
characters 
to console, _putch function, 595-596 
to streams, fputc and _fputchar functions, 301-302 
to streams, putc and putchar functions, 593-594 
data 
to files, write function, 887-888 
to streams, fwrite function, 338—339 
to strings, sprintf function, 725-726 
formatted output to argument lists, vfprintf, vprintf 
and vsprintf functions, 840—843 
integers to streams, _putw function, 603-604 
strings 
to output, puts function, 602 
to streams, fputs function, 303 
to the console, _cputs function, 167 
text 
horizontally, _pg_hlabelchart function, 569 
vertically, pg vlabelchart function, 576 
_wsetexit function, 889-891 
_wsetfocus function, 892-893 
_wsetscreenbuf function, 894—895 
_wsetsize function, 896-897 
_wyield function, 898-899 


X 


XENIX compatibility, ix 


Y 


_y0 function, 103-105 
_y0l function, 103—105 
_yl function, 103-105 
_yll function, 103-105 
_yn function, 103-105 
_ynl function, 103-105 


Microsofts Product Assistance Request 
Microsoft C/C++ Version 7.0 


Microsoft Product Support Services 
Phone (206) 635-7007 


Instructions 
If you should need assistance with a Microsoft product, you can contact our Product Support Services group 
through the CompuServee@ Information Service or by telephone. 


CompuServe is an electronic information service accessible by modem. If you have a CompuServe account, log 
on to the CompuServe Information Service and type Go Microsoft. You will see the Microsoft Connection 
menu, from which you can choose the forum that matches the information you need. To set up a CompuServe 
account, call CompuServe Customer Service at 800-848-8990 (or (614) 457-8650 in Ohio). 


If you want to telephone Product Support Services from the United States, call (206) 635-7007. If you are 
calling from another country, please contact the nearest Microsoft subsidiary. (The subsidiaries' phone numbers 
are on the preaddressed labels included in the package.) So that we can answer your questions as quickly as 
possible, please gather all information that applies to your problem. Note or print out any on-screen messages 
you get when the problem occurs. Have your manual and product disks close at hand and have available all the 
information requested on this form when you call. 


So that we can assist you more effectively, please be prepared to answer the following questions regarding 
your problem, your software, and your hardware. 


Diagnosing a Problem 


1 Can you reproduce the problem? 5 Which version of the linker are you using? (To 
LI yes LJ no display the version number on your screen, type 
LINK at the DOS prompt and press ENTER.) Is 


Steps to duplicate problem: there an older linker in your path? 


Version Number 


Product 


Name/Version Number 


2 Does the problem occur with another copy of . 
the original disk of your Microsoft software? Operating System 
J yes I no 


Name/Version Number 
3 Does the problem occur with another system 


(if available)? 


nies one Hardware 
Computer 
4 If you were running other windowing or 
memory-resident software at the same time, 
does the problem also occur when you don’t Nicene (2.9., 80386, 80486) 
use the other software? 


td yes I no Capacity (megabyte) 


Note: With DOS, you can run CHKDSK or MEM to 
determine the amount of memory available. With Microsoft 

Name/Version Number Windows™, choose About Program Manager from the Help 
menu to determine the amount of memory available. 


Name/Version Number 


Hardware (continued) 


= Floppy-disk drives 


Number: (1 412 (4 other 


=» Hard Disks 


Manufacturer/Model Capacity (megabyte) 


Manufacturer/Mode! 


Peripherals 
= Printer/Plotter 


Manufacturer/Model (J Serial (4 Parallel 


Printer peripherals, such as font cartridges, 
downloadable fonts, sheet feeders: 


= Mouse 
Microsoft Mouse: G Bus Q Serial @ InPorte 


I PS/2e@ O Other 


Manufacturer/Model 


= Boards 
(J Add-on RAM board/EMS boards 


Manufacturer/Model/Total Memory 


1 Graphics-adapter board 


Manufacturer/Model 


Capacity (megabyte) 


(4 Other boards installed 


Manufacturer/Model 


Manufacturer/Model 


= Modem 


Manufacturer/Model 


CD-ROM Player 


Manufacturer/Model 


Version of Microsoft MS-DOSe CD-ROM 
Extensions: 


Network 


Is your system part of a network? Ll yes J no 


Manufacturer/Model 


What software does your network use? What is the 
version number of that software? 


ADHESIVE 


EMOVE TO EXPOSE ADHESIVE 
REMOVE TO EXPOSE ADHESIVE 


ADHESIVE 


a ae a a I me SME RE 


REMOVE TO EXPOSE ADHESIVE 


REMOVE TO EXPOS 


we ee SI ek a een at aw ae St, atte, tte, 


Documentation Feedback — Microsofts C/C++ Version 7.0 


Help us improve our documentation. When you become familiar with this product, complete and return this 
form. Comments and suggestions become the property of Microsoft Corporation. 


Please answer the following questions about your 
programming background and practice. 
1. Years of programming experience: 

All languages (% C++ 


2. Occupation: 


3. How long have you used this product? 
Months 


4. What percentage of the time do you compile 
and link in one step using CL? 
Separately? 


5. What percentage of the time do you compile 
using full optimization (/Ox)? ____ Using 
ANSI compatibility (/Za)? ___. What other 
options do you use? 


6. What is the primary target operating system for 
your programs? DOS ____. Windows 
Other 


Please answer the following questions about the 
Microsoft Advisor Help system. 


1. Do you use the Microsoft Advisor Help 
system? Yes ___ No Why or why not? 


2. Can you find the information you need quickly 
and easily? Always ____ Most of the time ____ 
Some of the time Seldom 


3. What features would make it easier to find the 
information you need? 


Please answer the following questions about the 
printed documentation. 


1. Can you find the information you need quickly 
and easily? Always ____. Most of the time ____ 
Some of the time ___. Seldom 


2. Does the comprehensive index help you find 
the information you need? Yes No 


3. What features would make it easier to find the 


information you need? 


4. Does the organization of the Class Libraries 
Reference make it easy to use? Yes ___ 
No ___. Comments: 


5. Did the C++ tutorial Gn C++ Tutorial) 
introduce you to C++ programming? 
Yes No Comments: 


Did the PWB tutorial (in Environment and 
Tools) teach you to use the PWB environment? 
Yes No Comments: 


Did the Foundation Class Library tutorial (in 
Class Libraries User’ s Guide) teach you to 
program with the Microsoft class libraries? 
Yes__ No ____ Comments: 


List additional tutorials you need. 


6. Does the Cookbook section of the Class 
Libraries User’s Guide help you solve specific 
programming problems? Yes No 
Comments: 


7. Which chapters of Programming Techniques 
are most helpful? 
Least helpful? 
What other topics should be covered? 


8. Which parts of the printed documentation do 
you refer to most frequently? 


Least frequently? 


How well does the documentation meet your 
needs? Rate each from | (does not meet your 
needs at all) to 5 (meets your needs perfectly). 
____C Language Reference 

_____ Class Libraries Reference 

_____ Class Libraries User’ s Guide 

___. Comprehensive Index and Errors Reference 
____ C++ Language Reference 

____ C++ Tutorial 

____ Environment and Tools 

___. Getting Started 

____ Programming Techniques 

____ Run-Time Library Reference 

____ Source Profiler User’ s Guide 

____. Microsoft Advisor Help system 


Use the back of this form for additional suggestions and comments. Please note any errors and special 
strengths or weaknesses in areas such as programming examples, indexes, and overall organization. 


Name 


Address 


City/State/Zip 
( ) ( ) 
Phone (home) (work) 
May we contact you for additional information about your comments? Yes No 


Additional comments: 
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